fix(pptx): add slide number and depth to email addresses (#4534)

## What

Email addresses in PowerPoint files now get the same slide number and
heading depth as the text around them.

```
Before: {"type": "EmailAddress", "text": "sales@example.com", "metadata": {"filename": "deck.pptx"}}
After:  {"type": "EmailAddress", "text": "sales@example.com", "metadata": {"filename": "deck.pptx", "page_number": 2, "category_depth": 1}}
```

## Why

Every other text element on a slide was created with page and depth
metadata. Email addresses were the one case that was skipped, so
consumers could not tell which slide an email came from. Email detection
and the depth of nearby headings are unchanged.

## Notes for consumers

Element IDs change for PPTX email addresses, and for any element that
follows an email on the same slide. IDs are a hash that includes the
page number and the element's position on its page. Emails used to have
no page number, which also reset the position count for the elements
after them. Re-processing a deck that contains email addresses will
produce some new IDs, which matters if you upsert or deduplicate by
`element_id`.

## Validation

New tests cover two slides, a custom starting page, emails in titles and
body text, and both file and filename input. They fail on `main`. All 55
PPTX tests pass.

Author: CyMule

CHANGELOG.md

@@ -1,3 +1,10 @@
+## 0.27.22
+
+### Fixes
+
+- **Preserve slide and category-depth metadata on PPTX email addresses.** Emails in title and body shapes now receive the same text metadata as neighboring elements, including custom starting page numbers. Email classification and title-depth progression are unchanged. Element IDs change for these emails and for elements that follow an email on the same slide, because IDs include the page number and the element's position on its page.
+
+
 ## 0.27.21
 
 ### Fixes

scripts/ci/install-system-deps.sh

@@ -30,6 +30,14 @@ install_packages() {
   sudo apt-get "${apt_options[@]}" --no-download install -y "$@"
 }
 
+# GitHub's Azure mirror can stall large LibreOffice downloads. Use Ubuntu's
+# primary HTTPS mirror for both legacy and deb822 source files.
+for source_file in /etc/apt/sources.list /etc/apt/sources.list.d/*.list /etc/apt/sources.list.d/*.sources; do
+  if [[ -f "$source_file" ]]; then
+    sudo sed -i -E 's|https?://azure.archive.ubuntu.com/ubuntu|https://archive.ubuntu.com/ubuntu|g' "$source_file"
+  fi
+done
+
 retry_download apt-get "${apt_options[@]}" -o APT::Update::Error-Mode=any update
 if [[ "${1:-}" == "--packages-only" ]]; then
   shift

test_unstructured/partition/test_pptx.py

@@ -28,6 +28,7 @@
 from unstructured.documents.elements import (
     Element,
     ElementMetadata,
+    EmailAddress,
     Image,
     ListItem,
     NarrativeText,
@@ -797,3 +798,52 @@ def last_modified_prop_(self, request: FixtureRequest):
     @pytest.fixture()
     def metadata_file_path_prop_(self, request: FixtureRequest):
         return property_mock(request, PptxPartitionerOptions, "metadata_file_path")
+
+
+@pytest.mark.parametrize("input_kind", ["filename", "file"])
+def test_partition_pptx_preserves_email_slide_and_depth_metadata(tmp_path, input_kind):
+    presentation = pptx.Presentation()
+    for slide_number in range(2):
+        slide = presentation.slides.add_slide(presentation.slide_layouts[1])
+        title_frame = slide.shapes.title.text_frame
+        title_frame.text = "First heading"
+        title_frame.add_paragraph().text = f"title{slide_number}@example.com"
+        title_frame.add_paragraph().text = "Next heading"
+        body_frame = slide.placeholders[1].text_frame
+        body_frame.text = f"body{slide_number}@example.com"
+        body_frame.paragraphs[0].level = 2
+
+    filename = tmp_path / "emails.pptx"
+    presentation.save(filename)
+    kwargs = (
+        {"filename": str(filename)}
+        if input_kind == "filename"
+        else {
+            "file": io.BytesIO(filename.read_bytes()),
+            "metadata_filename": filename.name,
+        }
+    )
+    elements = partition_pptx(
+        **kwargs,
+        starting_page_number=10,
+        include_page_breaks=False,
+        metadata_last_modified="2024-04-02T20:32:35",
+        languages=["eng"],
+    )
+
+    emails = [element for element in elements if isinstance(element, EmailAddress)]
+    assert [(e.text, e.metadata.page_number, e.metadata.category_depth) for e in emails] == [
+        ("title0@example.com", 10, 1),
+        ("body0@example.com", 10, 2),
+        ("title1@example.com", 11, 1),
+        ("body1@example.com", 11, 2),
+    ]
+    assert all(e.metadata.filename == filename.name for e in emails)
+    assert all(e.metadata.last_modified == "2024-04-02T20:32:35" for e in emails)
+    titles = [element for element in elements if isinstance(element, Title)]
+    assert [(e.text, e.metadata.category_depth) for e in titles] == [
+        ("First heading", 0),
+        ("Next heading", 1),
+        ("First heading", 0),
+        ("Next heading", 1),
+    ]

unstructured/__version__.py

@@ -1 +1 @@
-__version__ = "0.27.21"  # pragma: no cover
+__version__ = "0.27.22"  # pragma: no cover

unstructured/partition/pptx.py

@@ -232,7 +232,7 @@ def _iter_shape_elements(self, shape: Shape) -> Iterator[Element]:
             if self._is_bulleted_paragraph(paragraph):
                 yield ListItem(text=text, metadata=metadata, detection_origin=DETECTION_ORIGIN)
             elif is_email_address(text):
-                yield EmailAddress(text=text, detection_origin=DETECTION_ORIGIN)
+                yield EmailAddress(text=text, metadata=metadata, detection_origin=DETECTION_ORIGIN)
             elif is_possible_narrative_text(text):
                 yield NarrativeText(
                     text=text,
@@ -290,7 +290,11 @@ def _iter_title_shape_element(self, shape: Shape) -> Iterator[Element]:
                     detection_origin=DETECTION_ORIGIN,
                 )
             elif is_email_address(text):
-                yield EmailAddress(text=text, detection_origin=DETECTION_ORIGIN)
+                yield EmailAddress(
+                    text=text,
+                    metadata=self._opts.text_metadata(category_depth=depth),
+                    detection_origin=DETECTION_ORIGIN,
+                )
             else:
                 # increment the category depth by the paragraph increment in the shape
                 yield Title(