feat: add create_file_from_elements() to re-create document files from elements

claytonlin1110 · claytonlin1110 · commit 1e6880c26178 · 2026-02-23T14:42:30.000-06:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,8 @@
+## 0.21.5
+
+### Enhancements
+- **Add `create_file_from_elements()` to re-create document files from elements (fixes #3994)**: New staging helper `create_file_from_elements(elements, format=..., filename=...)` converts a list of elements back into a document in the given format (`"markdown"`, `"html"`, or `"text"`), optionally writing to a file. Supports the workflow: partition → modify elements (e.g. replace Image with NarrativeText using alt text) → write back to file.
+
 ## 0.21.4
 - Add a github action for testing time regressions
 
diff --git a/test_unstructured/staging/test_base.py b/test_unstructured/staging/test_base.py
@@ -664,6 +664,48 @@ def test_elements_to_md_file_output():
             os.unlink(tmp_filename)
 
 
+def test_create_file_from_elements_markdown():
+    """Test create_file_from_elements with format=markdown returns and optionally writes file."""
+    elements = [Title("Heading"), NarrativeText("Some body text.")]
+    content = base.create_file_from_elements(elements, format="markdown")
+    assert content == "# Heading\nSome body text."
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".md", delete=False) as tmp_file:
+        tmp_filename = tmp_file.name
+    try:
+        out = base.create_file_from_elements(elements, format="markdown", filename=tmp_filename)
+        assert out == content
+        with open(tmp_filename) as f:
+            assert f.read() == content
+    finally:
+        if os.path.exists(tmp_filename):
+            os.unlink(tmp_filename)
+
+
+def test_create_file_from_elements_text():
+    """Test create_file_from_elements with format=text."""
+    elements = [Title("A"), NarrativeText("B")]
+    content = base.create_file_from_elements(elements, format="text")
+    assert content == "A\nB"
+
+
+def test_create_file_from_elements_html():
+    """Test create_file_from_elements with format=html returns HTML."""
+    elements = [Title("Page"), NarrativeText("Content")]
+    content = base.create_file_from_elements(elements, format="html")
+    assert "<!DOCTYPE html" in content
+    assert "<body>" in content
+    assert "Page" in content
+    assert "Content" in content
+
+
+def test_create_file_from_elements_unsupported_format():
+    """Test create_file_from_elements raises for unsupported format."""
+    elements = [Title("X")]
+    with pytest.raises(ValueError, match="Unsupported format"):
+        base.create_file_from_elements(elements, format="pdf")
+
+
 def test_element_to_md_with_none_mime_type():
     """Test element_to_md handles None mime_type gracefully."""
     from unstructured.documents.elements import ElementMetadata, Image
diff --git a/unstructured/__version__.py b/unstructured/__version__.py
@@ -1 +1 @@
-__version__ = "0.21.4"  # pragma: no cover
+__version__ = "0.21.5"  # pragma: no cover
diff --git a/unstructured/staging/base.py b/unstructured/staging/base.py
@@ -195,6 +195,72 @@ def elements_to_md(
     return markdown_content
 
 
+def create_file_from_elements(
+    elements: Iterable[Element],
+    format: str = "markdown",
+    filename: Optional[str] = None,
+    encoding: str = "utf-8",
+    exclude_binary_image_data: bool = False,
+    no_group_by_page: bool = False,
+) -> str:
+    """Re-create a document file from a list of elements (reverse of partition).
+
+    Use this after partitioning a document, optionally modifying elements (e.g. replacing
+    Image elements with NarrativeText using alt text), then writing back to a file.
+
+    Supported formats: "markdown", "html", "text".
+
+    Args:
+        elements: Iterable of elements to convert (e.g. from partition_* or after editing).
+        format: Output format: "markdown", "html", or "text".
+        filename: Optional path to write the document to.
+        encoding: File encoding when writing to file.
+        exclude_binary_image_data: If True, omit base64 image data (markdown/html).
+        no_group_by_page: If True, do not group HTML output by page.
+
+    Returns:
+        The document content as a string.
+
+    Example:
+        >>> from unstructured.partition.md import partition_md
+        >>> from unstructured.staging.base import create_file_from_elements
+        >>> elements = partition_md("README.md")
+        >>> # ... modify elements (e.g. replace Image with NarrativeText) ...
+        >>> create_file_from_elements(elements, format="markdown", filename="out.md")
+    """
+    format_lower = format.strip().lower()
+    if format_lower not in ("markdown", "html", "text"):
+        raise ValueError(
+            f"Unsupported format: {format!r}. Supported formats: 'markdown', 'html', 'text'."
+        )
+
+    if format_lower == "markdown":
+        content = elements_to_md(
+            elements,
+            filename=None,
+            exclude_binary_image_data=exclude_binary_image_data,
+            encoding=encoding,
+        )
+    elif format_lower == "html":
+        from unstructured.partition.html.convert import elements_to_html
+
+        content = elements_to_html(
+            list(elements),
+            exclude_binary_image_data=exclude_binary_image_data,
+            no_group_by_page=no_group_by_page,
+        )
+    else:
+        # text
+        content = elements_to_text(elements, filename=None, encoding=encoding)
+        assert content is not None  # we passed filename=None
+
+    if filename is not None:
+        with open(filename, "w", encoding=encoding) as f:
+            f.write(content)
+
+    return content
+
+
 def elements_to_json(
     elements: Iterable[Element],
     filename: Optional[str] = None,

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-__version__ = "0.21.4" # pragma: no cover`
	`1`	`+__version__ = "0.21.5" # pragma: no cover`