feat(custom_xml): add string-blob helpers and integration tests

Phase 4 of customXml support per Plans/customxml-implementation-plan.md.

String-blob helpers (plan section 2.3)
--------------------------------------
- CustomXmlParts.add_string_blob(name, content, *, mime_hint, encoding, scope)
  wraps a string payload in a <blob xmlns='urn:python-pptx:blob' name=...
  encoding=text|base64 mime=...> envelope, then attaches it via add(...).
  Caller pre-encodes binary content; helper does NOT auto-base64.
- CustomXmlParts.read_string_blob(name) reverse-resolves by name and returns
  the envelope text, or None if absent / not-our-envelope.
- CustomXmlParts.blob_encoding(name) for callers mixing text and base64
  blobs that need the original encoding to decode on read.

Integration fixtures
--------------------
Four synthetic .pptx files generated by our own API live at
tests/test_files/customxml/:

- presentation-scoped.pptx — Office.js / Word default topology
- package-scoped.pptx       — VSTO / SharePoint topology
- multipart.pptx            — every Phase 1-4 surface in one file
- clean.pptx                — regression baseline; no customXml at all

The generation script at tests/test_files/customxml/_generate_fixtures.py
re-creates them deterministically (GUIDs pinned). README.rst documents what
each fixture exercises and notes that real third-party fixtures from
SharePoint/Office.js/VSTO will land later during the manual PowerPoint UI
matrix in plan section 5.4.

Integration tests (tests/integration/test_customxml_roundtrip.py) load each
fixture, exercise the public API against it, save through BytesIO, reload,
and assert state survives. Covers payload preservation, GUID/schema_refs
preservation, scope-topology preservation through save, mutation +
round-trip, removal, core_properties coexistence, and the
'no customXml at all' regression case.

Counts
------
- 10 new string-blob unit tests in tests/test_custom_xml.py
- 20 new integration tests in tests/integration/test_customxml_roundtrip.py
- Total tests now: 2986 passed (2956 baseline + 30 new)

Author: Matthew Horoszowski

src/pptx/custom_xml.py

@@ -27,6 +27,11 @@
 # `{prefix}{datastore_item_id}` and the value is the user-assigned name.
 NAME_PROPERTY_PREFIX = "_pptx_customxml_name_"
 
+# Reserved namespace for the string-blob envelope written by `add_string_blob`.
+# Read back through `read_string_blob` only — callers using `add(...)` directly
+# should pick their own namespace, not this one.
+BLOB_NAMESPACE = "urn:python-pptx:blob"
+
 
 class CustomXmlParts(Sequence[CustomXmlPart]):
     """Collection of customXml data parts attached to the presentation.
@@ -145,6 +150,86 @@ def add(
 
         return data_part
 
+    def add_string_blob(
+        self,
+        name: str,
+        content: str,
+        *,
+        mime_hint: str | None = None,
+        encoding: Literal["text", "base64"] = "text",
+        scope: Literal["presentation", "package"] = "presentation",
+    ) -> CustomXmlPart:
+        """Embed a string payload as a customXml part.
+
+        Wraps `content` in a one-element XML envelope under the reserved
+        `urn:python-pptx:blob` namespace::
+
+            <blob xmlns="urn:python-pptx:blob"
+                  name="…" mime="…" encoding="text|base64">…</blob>
+
+        For binary or non-XML-safe text, set ``encoding="base64"`` and pass
+        already-encoded `content` — the helper does NOT encode for you. Read
+        back via :meth:`read_string_blob`.
+
+        `mime_hint` is stored as the ``mime`` attribute on the envelope and
+        round-trips for the caller's reference; it has no effect on PowerPoint.
+
+        Returns the created :class:`CustomXmlPart`. Already attached at the
+        chosen scope; nothing else is needed before ``prs.save(...)``.
+        """
+        if not isinstance(name, str) or not name:
+            raise ValueError("name must be a non-empty string")
+        if not isinstance(content, str):  # pyright: ignore[reportUnnecessaryIsInstance]
+            raise TypeError("content must be str, got %s" % type(content).__name__)
+        if encoding not in ("text", "base64"):
+            raise ValueError(
+                "encoding must be 'text' or 'base64', got %r" % (encoding,)
+            )
+
+        from lxml import etree
+
+        envelope = etree.Element("{%s}blob" % BLOB_NAMESPACE, nsmap={None: BLOB_NAMESPACE})
+        envelope.set("name", name)
+        envelope.set("encoding", encoding)
+        if mime_hint is not None:
+            envelope.set("mime", mime_hint)
+        envelope.text = content
+
+        return self.add(envelope, name=name, scope=scope)
+
+    def read_string_blob(self, name: str) -> str | None:
+        """Return the string payload of the blob part `name`, or `None`.
+
+        Locates the part via :meth:`by_name`. Returns `None` if no such part
+        exists or if the part is not a `urn:python-pptx:blob` envelope (i.e.
+        was added by some other API or tool).
+
+        For ``encoding="base64"`` blobs, the still-encoded string is returned
+        — the caller decodes. The original encoding is recoverable from
+        :meth:`blob_encoding`.
+        """
+        part = self.by_name(name)
+        if part is None:
+            return None
+        root = part.element
+        if root.tag != "{%s}blob" % BLOB_NAMESPACE:
+            return None
+        return root.text or ""
+
+    def blob_encoding(self, name: str) -> str | None:
+        """Return the `encoding` attribute of the blob part `name`, or `None`.
+
+        Useful when a caller mixes text and base64 blobs and needs to decode
+        the latter on read.
+        """
+        part = self.by_name(name)
+        if part is None:
+            return None
+        root = part.element
+        if root.tag != "{%s}blob" % BLOB_NAMESPACE:
+            return None
+        return root.get("encoding")
+
     def remove(self, part: Union[CustomXmlPart, int, str]) -> None:
         """Remove a customXml part from the presentation.
 

tests/integration/__init__.py

@@ -0,0 +1,204 @@
+# pyright: reportPrivateUsage=false
+
+"""Integration test suite for customXml round-trip.
+
+Loads each synthetic fixture under ``tests/test_files/customxml/``, exercises
+the public API against it, saves to a fresh BytesIO, reloads, and asserts the
+state survived.
+
+Real third-party fixtures (SharePoint-saved, Office.js-produced, VSTO-tooled)
+will land later under ``sharepoint-saved.pptx`` etc. once captured during the
+manual PowerPoint UI matrix in ``Plans/customxml-implementation-plan.md`` §5.4.
+"""
+
+from __future__ import annotations
+
+import os
+from io import BytesIO
+
+import pytest
+
+from pptx import Presentation
+from pptx.opc.constants import RELATIONSHIP_TYPE as RT
+from pptx.parts.custom_xml import CustomXmlPart
+
+
+_FIXTURE_DIR = os.path.join(
+    os.path.dirname(os.path.abspath(__file__)),
+    os.pardir,
+    "test_files",
+    "customxml",
+)
+
+
+def _fixture(name: str) -> str:
+    return os.path.join(_FIXTURE_DIR, name)
+
+
+def _roundtrip(prs):
+    buf = BytesIO()
+    prs.save(buf)
+    buf.seek(0)
+    return Presentation(buf)
+
+
+class DescribePresentationScopedFixture:
+    def it_loads_the_part(self):
+        prs = Presentation(_fixture("presentation-scoped.pptx"))
+        assert len(prs.custom_xml_parts) == 1
+
+    def it_upgrades_loaded_part_to_CustomXmlPart_class(self):
+        prs = Presentation(_fixture("presentation-scoped.pptx"))
+        part = prs.custom_xml_parts[0]
+        assert isinstance(part, CustomXmlPart)
+
+    def it_preserves_the_payload(self):
+        prs = Presentation(_fixture("presentation-scoped.pptx"))
+        part = prs.custom_xml_parts.by_name("provenance")
+        assert part is not None
+        assert part.element.tag == "{urn:my:provenance}provenance"
+        source = part.element.find("{urn:my:provenance}source")
+        assert source is not None
+        assert source.text == "integration-fixture"
+
+    def it_preserves_the_pinned_guid(self):
+        prs = Presentation(_fixture("presentation-scoped.pptx"))
+        part = prs.custom_xml_parts[0]
+        assert part.datastore_item_id == "{1A2B3C4D-5E6F-7890-ABCD-EF1234567890}"
+
+    def it_preserves_the_schema_refs(self):
+        prs = Presentation(_fixture("presentation-scoped.pptx"))
+        part = prs.custom_xml_parts[0]
+        assert part.schema_refs == ("urn:my:provenance",)
+
+    def it_preserves_the_presentation_scope_through_save(self):
+        prs = Presentation(_fixture("presentation-scoped.pptx"))
+        reloaded = _roundtrip(prs)
+        prs_rel_types = {r.reltype for r in reloaded.part.rels.values()}
+        pkg_rel_types = {r.reltype for r in reloaded.part.package._rels.values()}
+        assert RT.CUSTOM_XML in prs_rel_types
+        assert RT.CUSTOM_XML not in pkg_rel_types
+
+
+class DescribePackageScopedFixture:
+    def it_loads_the_part(self):
+        prs = Presentation(_fixture("package-scoped.pptx"))
+        assert len(prs.custom_xml_parts) == 1
+
+    def it_preserves_the_payload(self):
+        prs = Presentation(_fixture("package-scoped.pptx"))
+        part = prs.custom_xml_parts.by_name("vsto")
+        assert part is not None
+        assert part.element.tag == "{urn:my:vsto}vsto-config"
+
+    def it_preserves_the_package_scope_through_save(self):
+        prs = Presentation(_fixture("package-scoped.pptx"))
+        reloaded = _roundtrip(prs)
+        prs_rel_types = {r.reltype for r in reloaded.part.rels.values()}
+        pkg_rel_types = {r.reltype for r in reloaded.part.package._rels.values()}
+        assert RT.CUSTOM_XML in pkg_rel_types
+        assert RT.CUSTOM_XML not in prs_rel_types
+
+    def it_preserves_the_pinned_guid(self):
+        prs = Presentation(_fixture("package-scoped.pptx"))
+        part = prs.custom_xml_parts[0]
+        assert part.datastore_item_id == "{ABCDEF12-3456-7890-ABCD-EF1234567890}"
+
+
+class DescribeMultipartFixture:
+    def it_loads_two_customxml_parts_at_mixed_scopes(self):
+        prs = Presentation(_fixture("multipart.pptx"))
+        assert len(prs.custom_xml_parts) == 2 + 1  # provenance + extra + readme blob
+
+    def it_preserves_custom_document_properties(self):
+        prs = Presentation(_fixture("multipart.pptx"))
+        assert prs.custom_properties["Source"] == "deck-builder-cli@1.4.2"
+        assert prs.custom_properties["BuildNumber"] == 42
+        assert prs.custom_properties["IsDraft"] is True
+
+    def it_finds_each_part_by_name(self):
+        prs = Presentation(_fixture("multipart.pptx"))
+        assert prs.custom_xml_parts.by_name("provenance") is not None
+        assert prs.custom_xml_parts.by_name("extra") is not None
+        assert prs.custom_xml_parts.by_name("readme") is not None
+
+    def it_round_trips_through_save_load_with_mutations(self):
+        prs = Presentation(_fixture("multipart.pptx"))
+        # mutate something in each layer
+        prs.custom_properties["NewKey"] = "added"
+        prs.custom_xml_parts.by_name("provenance").add_item(
+            "added-by-test", "value"
+        )
+
+        reloaded = _roundtrip(prs)
+
+        assert reloaded.custom_properties["NewKey"] == "added"
+        assert reloaded.custom_properties["Source"] == "deck-builder-cli@1.4.2"
+        prov = reloaded.custom_xml_parts.by_name("provenance")
+        assert prov is not None
+        # The added child element survived the round-trip
+        added = [c for c in prov.element if c.tag.endswith("added-by-test")]
+        assert len(added) == 1
+        assert added[0].text == "value"
+
+    def it_round_trips_the_string_blob_helper(self):
+        prs = Presentation(_fixture("multipart.pptx"))
+        content = prs.custom_xml_parts.read_string_blob("readme")
+        assert content is not None
+        assert "# Hello" in content
+        assert "markdown content" in content
+
+    def it_remove_then_save_drops_the_part(self):
+        prs = Presentation(_fixture("multipart.pptx"))
+        provenance = prs.custom_xml_parts.by_name("provenance")
+        prs.custom_xml_parts.remove(provenance)
+        reloaded = _roundtrip(prs)
+        assert reloaded.custom_xml_parts.by_name("provenance") is None
+        # Other parts still present
+        assert reloaded.custom_xml_parts.by_name("extra") is not None
+        assert reloaded.custom_xml_parts.by_name("readme") is not None
+
+
+class DescribeCleanFixture:
+    """A presentation with no customXml at all should have no related rels."""
+
+    def it_has_no_customxml_parts(self):
+        prs = Presentation(_fixture("clean.pptx"))
+        assert len(prs.custom_xml_parts) == 0
+
+    def it_round_trips_with_no_rels_added(self):
+        prs = Presentation(_fixture("clean.pptx"))
+        # do nothing
+        reloaded = _roundtrip(prs)
+        prs_rel_types = {r.reltype for r in reloaded.part.rels.values()}
+        pkg_rel_types = {r.reltype for r in reloaded.part.package._rels.values()}
+        assert RT.CUSTOM_XML not in prs_rel_types
+        assert RT.CUSTOM_XML not in pkg_rel_types
+        assert RT.CUSTOM_PROPERTIES not in pkg_rel_types
+
+    def it_can_have_customxml_added_after_loading(self):
+        prs = Presentation(_fixture("clean.pptx"))
+        prs.custom_xml_parts.add(
+            b'<after-load xmlns="u:al"/>',
+            name="after-load",
+        )
+        reloaded = _roundtrip(prs)
+        part = reloaded.custom_xml_parts.by_name("after-load")
+        assert part is not None
+        assert part.element.tag == "{u:al}after-load"
+
+
+class DescribeCoreAndCustomCoexistence:
+    def it_preserves_core_properties_alongside_custom_ones(self):
+        prs = Presentation(_fixture("multipart.pptx"))
+        prs.core_properties.author = "Athena"
+        prs.core_properties.subject = "Integration test"
+
+        reloaded = _roundtrip(prs)
+
+        assert reloaded.core_properties.author == "Athena"
+        assert reloaded.core_properties.subject == "Integration test"
+        # custom properties still intact
+        assert reloaded.custom_properties["Source"] == "deck-builder-cli@1.4.2"
+        # customXml parts still intact
+        assert len(reloaded.custom_xml_parts) == 3

tests/integration/test_customxml_roundtrip.py

@@ -231,6 +231,67 @@ def it_supports_add_item_convenience(self, empty_prs):
         assert children[1].get("priority") == "high"
 
 
+class DescribeCustomXmlParts_string_blob:
+    def it_adds_a_string_blob(self, empty_prs):
+        part = empty_prs.custom_xml_parts.add_string_blob(
+            "readme", "# Hello\nworld", mime_hint="text/markdown"
+        )
+        assert isinstance(part, CustomXmlPart)
+        assert part.element.tag == "{urn:python-pptx:blob}blob"
+        assert part.element.get("name") == "readme"
+        assert part.element.get("mime") == "text/markdown"
+        assert part.element.get("encoding") == "text"
+        assert part.element.text == "# Hello\nworld"
+
+    def it_reads_back_a_string_blob_by_name(self, empty_prs):
+        empty_prs.custom_xml_parts.add_string_blob("note", "secret message")
+        assert empty_prs.custom_xml_parts.read_string_blob("note") == "secret message"
+
+    def it_returns_None_for_missing_blob(self, empty_prs):
+        assert empty_prs.custom_xml_parts.read_string_blob("missing") is None
+
+    def it_returns_None_for_a_non_blob_part(self, empty_prs):
+        empty_prs.custom_xml_parts.add(b'<other xmlns="u:o"/>', name="other")
+        # name lookup finds the part, but it's not the blob envelope shape
+        assert empty_prs.custom_xml_parts.read_string_blob("other") is None
+        assert empty_prs.custom_xml_parts.blob_encoding("other") is None
+
+    def it_round_trips_a_string_blob(self, empty_prs):
+        empty_prs.custom_xml_parts.add_string_blob("md", "content")
+        reloaded = _roundtrip(empty_prs)
+        assert reloaded.custom_xml_parts.read_string_blob("md") == "content"
+        assert reloaded.custom_xml_parts.blob_encoding("md") == "text"
+
+    def it_supports_base64_encoding(self, empty_prs):
+        encoded = "aGVsbG8gd29ybGQ="  # b64 of "hello world"
+        empty_prs.custom_xml_parts.add_string_blob("bin", encoded, encoding="base64")
+        assert empty_prs.custom_xml_parts.read_string_blob("bin") == encoded
+        assert empty_prs.custom_xml_parts.blob_encoding("bin") == "base64"
+
+    def it_rejects_empty_name(self, empty_prs):
+        with pytest.raises(ValueError):
+            empty_prs.custom_xml_parts.add_string_blob("", "content")
+
+    def it_rejects_non_string_content(self, empty_prs):
+        with pytest.raises(TypeError):
+            empty_prs.custom_xml_parts.add_string_blob("x", 42)  # type: ignore[arg-type]
+
+    def it_rejects_unknown_encoding(self, empty_prs):
+        with pytest.raises(ValueError):
+            empty_prs.custom_xml_parts.add_string_blob(
+                "x", "content", encoding="utf-7"  # type: ignore[arg-type]
+            )
+
+    def it_supports_package_scope(self, empty_prs):
+        from pptx.opc.constants import RELATIONSHIP_TYPE as RT_
+
+        empty_prs.custom_xml_parts.add_string_blob(
+            "x", "content", scope="package"
+        )
+        rel_types = {r.reltype for r in empty_prs.part.package._rels.values()}
+        assert RT_.CUSTOM_XML in rel_types
+
+
 class DescribeCustomXmlPart_name_edge_cases:
     def it_returns_None_when_no_name_property_for_the_guid(self, empty_prs):
         # Add a part WITHOUT a name. .name should return None even though the