feat: add group_elements_by_parent_id utility function (#4207)

Add a utility function to group elements by their parent_id metadata
field. This allows users to easily traverse document hierarchy by
grouping elements that share the same parent.

Includes an optional 'assign_orphans' parameter that, when True, assigns
elements with no parent_id to the same group as the previous element.

Fixes #1489

Author: MkDev11

CHANGELOG.md

@@ -1,3 +1,8 @@
+## 0.18.33-dev0
+
+### Enhancements
+- **Add `group_elements_by_parent_id` utility function**: Groups elements by their `parent_id` metadata field for easier document hierarchy traversal (fixes #1489)
+
 ## 0.18.32
 
 ### Enhancements
@@ -33,10 +38,6 @@
 - **Fix EN DASH not cleaned by `clean_bullets`**: Added EN DASH (`\u2013`) to `UNICODE_BULLETS` pattern so `clean_bullets` properly removes EN DASH bullet points without requiring `clean_dashes` (fixes #4105)
 - **Change `languages` parameter default from `["auto"]` to `None`**: Updated default value in `detect_languages()` and `partition_epub()` functions. Behavior unchanged as `None` is converted to `["auto"]` internally. (fixes #2471)
 - Resolve GHSA-58pv-8j8x-9vj2
-
-## 0.18.29
-
-### Enhancement
 - use render mode data to determine if a character extracted by pdfminer is invisible or not
 
 ## 0.18.28

test_unstructured/test_utils.py

@@ -331,3 +331,55 @@ def test_calculate_shared_ngram_percentage_returns_null_vals_for_empty_str():
     percent, common_ngrams = utils.calculate_shared_ngram_percentage(str1, str2, n)
     assert percent == 0
     assert not bool(common_ngrams)
+
+
+class DescribeGroupElementsByParentId:
+    """Unit tests for group_elements_by_parent_id function."""
+
+    def it_groups_elements_by_parent_id_with_orphans_in_none_group(self):
+        e1 = Title("Title 1")
+        e1.metadata.parent_id = "parent_A"
+        e2 = NarrativeText("Child of A")
+        e2.metadata.parent_id = "parent_A"
+        e3 = NarrativeText("Orphan 1")  # parent_id = None
+        e4 = Title("Title 2")
+        e4.metadata.parent_id = "parent_B"
+        e5 = NarrativeText("Orphan 2")  # parent_id = None
+
+        elements = [e1, e2, e3, e4, e5]
+        result = utils.group_elements_by_parent_id(elements)
+
+        assert list(result.keys()) == ["parent_A", None, "parent_B"]
+        assert [e.text for e in result["parent_A"]] == ["Title 1", "Child of A"]
+        assert [e.text for e in result[None]] == ["Orphan 1", "Orphan 2"]
+        assert [e.text for e in result["parent_B"]] == ["Title 2"]
+
+    def it_assigns_orphans_to_previous_element_group_when_assign_orphans_is_true(self):
+        e1 = Title("Title 1")
+        e1.metadata.parent_id = "parent_A"
+        e2 = NarrativeText("Child of A")
+        e2.metadata.parent_id = "parent_A"
+        e3 = NarrativeText("Orphan 1")  # parent_id = None
+        e4 = Title("Title 2")
+        e4.metadata.parent_id = "parent_B"
+        e5 = NarrativeText("Orphan 2")  # parent_id = None
+
+        elements = [e1, e2, e3, e4, e5]
+        result = utils.group_elements_by_parent_id(elements, assign_orphans=True)
+
+        assert list(result.keys()) == ["parent_A", "parent_B"]
+        assert [e.text for e in result["parent_A"]] == ["Title 1", "Child of A", "Orphan 1"]
+        assert [e.text for e in result["parent_B"]] == ["Title 2", "Orphan 2"]
+
+    def it_keeps_first_orphan_in_none_group_when_assign_orphans_is_true(self):
+        e1 = NarrativeText("First orphan")  # parent_id = None
+        e2 = Title("Title 1")
+        e2.metadata.parent_id = "parent_A"
+        e3 = NarrativeText("Orphan 2")  # parent_id = None
+
+        elements = [e1, e2, e3]
+        result = utils.group_elements_by_parent_id(elements, assign_orphans=True)
+
+        assert list(result.keys()) == [None, "parent_A"]
+        assert [e.text for e in result[None]] == ["First orphan"]
+        assert [e.text for e in result["parent_A"]] == ["Title 1", "Orphan 2"]

unstructured/__version__.py

@@ -1 +1 @@
-__version__ = "0.18.32"  # pragma: no cover
+__version__ = "0.18.33-dev0"  # pragma: no cover

unstructured/utils.py

@@ -746,6 +746,50 @@ def catch_overlapping_and_nested_bboxes(
     return document_with_overlapping_flag, overlapping_cases
 
 
+def group_elements_by_parent_id(
+    elements: Iterable["Element"],
+    assign_orphans: bool = False,
+) -> dict[Optional[str], list["Element"]]:
+    """Group elements by their parent_id metadata field.
+
+    Elements with the same parent_id are grouped together.
+
+    Args:
+        elements: An iterable of Element objects to group.
+        assign_orphans: If True, elements with no parent_id (None) will be assigned to
+            the same group as the previous element. If False (default), elements with
+            no parent are grouped under the None key.
+
+    Returns:
+        A dictionary mapping parent_id values to lists of elements sharing that parent_id.
+
+    Example:
+        >>> elements = partition("example.pdf")
+        >>> grouped = group_elements_by_parent_id(elements)
+        >>> for parent_id, children in grouped.items():
+        ...     print(f"Parent {parent_id}: {len(children)} children")
+
+        >>> # Assign orphan elements to previous element's group
+        >>> grouped = group_elements_by_parent_id(elements, assign_orphans=True)
+    """
+    from collections import defaultdict
+
+    groups: dict[Optional[str], list["Element"]] = defaultdict(list)
+    last_parent_id: Optional[str] = None
+
+    for element in elements:
+        parent_id = getattr(element.metadata, "parent_id", None)
+
+        if parent_id is None and assign_orphans:
+            parent_id = last_parent_id
+        elif parent_id is not None:
+            last_parent_id = parent_id
+
+        groups[parent_id].append(element)
+
+    return dict(groups)
+
+
 class FileHandler:
     def __init__(self, file_path: str):
         self.file_path = file_path