⚡️ Speed up function element_to_md by 38%

[codeflash-ai]

📄 38% (0.38x) speedup for element_to_md in unstructured/staging/base.py

⏱️ Runtime : 1.31 milliseconds → 947 microseconds (best of 35 runs)

📝 Explanation and details

The optimized code achieves a 38% speedup by replacing Python's match/case pattern matching with explicit isinstance() type checks and early returns.

Key Optimization

Pattern matching overhead elimination: Python's match/case statement (introduced in Python 3.10) performs complex pattern matching that includes:

• Attribute extraction (Title(text=text))
• Guard clause evaluation (multiple if conditions)
• Sequential case evaluation even after finding a match

The optimized version uses direct isinstance() checks which are significantly faster primitive type checks in Python's C implementation.

Performance Analysis from Line Profiler

Looking at the line profiler results:

• Original: Pattern matching lines show 9-17% time spent on case matching alone (lines with case Title, case Table, case Image)
• Optimized: The isinstance() checks are 2-3x faster, consolidating what were multiple pattern match evaluations into single type checks

For example, the Title case:

• Original: 1.81ms (16.4% of total time) on pattern match + 264μs on return
• Optimized: 1.66ms (20.9% of total time) on isinstance check + 298μs on return - but overall function is faster

Why This Matters

Based on function_references, this function is called from elements_to_md() in a list comprehension over all elements. This means:

1. Hot path: The function is called once per element in potentially large document conversions
2. Multiplicative effect: A 38% speedup per call compounds significantly when processing hundreds or thousands of elements (as shown in the large-scale test with 500 elements)
3. Real-world impact: Document processing workloads converting entire documents to markdown will see proportional performance improvements

Test Results Confirm Optimization

The annotated tests show consistent improvements across all element types:

• Title elements: 82-93% faster (simple case benefits most from avoiding pattern matching)
• Table elements: 21-36% faster
• Image elements: 8-54% faster (varying based on metadata complexity)

The optimization is particularly effective for simpler cases (Title) where pattern matching overhead is proportionally higher relative to the work done.

✅ Correctness verification report:

Test	Status
⚙️ Existing Unit Tests	✅ 43 Passed
🌀 Generated Regression Tests	✅ 408 Passed
⏪ Replay Tests	🔘 None Found
🔎 Concolic Coverage Tests	✅ 1 Passed
📊 Tests Coverage	100.0%

⚙️ Click to see Existing Unit Tests

Test File::Test Function	Original ⏱️	Optimized ⏱️	Speedup
staging/test_base.py::test_element_to_md_conversion	48.9μs	36.5μs	34.1%✅
staging/test_base.py::test_element_to_md_with_none_mime_type	9.68μs	9.10μs	6.41%✅

🌀 Click to see Generated Regression Tests

from unstructured.documents.elements import Image, Table, Title
from unstructured.staging.base import element_to_md


def test_title_renders_as_markdown_header():
    # Create a Title element with simple text and verify the markdown header formatting.
    t = Title("Hello World")
    # The function should produce a level-1 markdown header with a single space after '#'.
    codeflash_output = element_to_md(t)  # 1.84μs -> 989ns (85.7% faster)


def test_title_preserves_markdown_characters():
    # Verify that special markdown characters in the title text are preserved verbatim.
    t = Title("**bold** _italic_ `code`")
    # No escaping is done by element_to_md, so the returned string should include the raw markdown.
    codeflash_output = element_to_md(t)  # 1.83μs -> 989ns (84.6% faster)


def test_table_with_text_as_html_returns_html():
    # Table elements should return metadata.text_as_html when it is not None.
    tb = Table("ignored text")
    # Assign HTML to the table's metadata. The implementation checks for "is not None"
    # so an empty string would also be returned; here we use non-empty HTML.
    tb.metadata.text_as_html = "<table><tr><td>1</td></tr></table>"
    codeflash_output = element_to_md(tb)  # 3.14μs -> 2.30μs (36.4% faster)


def test_table_with_empty_string_text_as_html_returns_empty_string():
    # If metadata.text_as_html is an empty string (but not None), it should be returned.
    tb = Table("table text fallback")
    tb.metadata.text_as_html = ""  # empty but not None -> should return empty string
    codeflash_output = element_to_md(tb)  # 3.08μs -> 2.26μs (36.4% faster)


def test_table_without_text_as_html_returns_element_text():
    # If metadata.text_as_html is None, the function should fall back to returning element.text.
    tb = Table("table text fallback")
    # Ensure the attribute is explicitly None to mimic the fallback path.
    tb.metadata.text_as_html = None
    codeflash_output = element_to_md(tb)  # 9.95μs -> 7.75μs (28.5% faster)


def test_image_with_base64_and_no_mime_returns_wildcard_mime():
    # When image_base64 is present and image_mime_type is None, the function must use image/*.
    img = Image("alt text")
    img.metadata.image_base64 = "R0lGODlh"  # short dummy base64 snippet
    img.metadata.image_mime_type = None
    # The default for exclude_binary_image_data is False, so binary data should be included.
    expected = "![alt text](data:image/*;base64,R0lGODlh)"
    codeflash_output = element_to_md(img)  # 9.65μs -> 8.57μs (12.6% faster)


def test_image_with_base64_and_mime_returns_specific_mime():
    # When both image_base64 and image_mime_type are present, the function must use the provided mime.
    img = Image("logo")
    img.metadata.image_base64 = "aGVsbG8="  # "hello" in base64
    img.metadata.image_mime_type = "image/png"
    expected = "![logo](data:image/png;base64,aGVsbG8=)"
    codeflash_output = element_to_md(img)  # 4.74μs -> 3.08μs (54.0% faster)


def test_image_with_url_returns_url_when_no_base64():
    # If there is no image_base64, but image_url is present, the function should return a markdown image link to the URL.
    img = Image("diagram")
    img.metadata.image_base64 = None
    img.metadata.image_mime_type = None
    img.metadata.image_url = "https://example.com/diagram.png"
    expected = "![diagram](https://example.com/diagram.png)"
    codeflash_output = element_to_md(img)  # 11.8μs -> 8.72μs (35.3% faster)


def test_exclude_binary_image_data_prevents_base64_inclusion():
    # If exclude_binary_image_data is True, base64 image cases should not be used.
    img = Image("should fall back")
    img.metadata.image_base64 = "ZmFrZQ=="  # "fake" in base64
    img.metadata.image_mime_type = None
    img.metadata.image_url = None
    # With exclusion requested, binary data paths are skipped and the function should fall back to element.text.
    codeflash_output = element_to_md(
        img, exclude_binary_image_data=True
    )  # 11.9μs -> 8.61μs (38.1% faster)


def test_image_prefers_base64_over_url_when_base64_present():
    # When both image_base64 and image_url are present, the function's order should prefer base64 cases first.
    img = Image("both")
    img.metadata.image_base64 = "AAA"
    img.metadata.image_mime_type = "image/gif"
    img.metadata.image_url = "https://example.com/should-not-be-used.png"
    # Because base64 is present and exclude_binary_image_data is False by default, base64 branch should be used.
    codeflash_output = element_to_md(img)  # 4.67μs -> 3.15μs (48.3% faster)


def test_image_with_no_metadata_fields_returns_text():
    # If none of the image metadata fields used by the function are set, element.text should be returned unchanged.
    img = Image("plain image text")
    # Explicitly clear commonly checked metadata fields to exercise fallback.
    img.metadata.image_base64 = None
    img.metadata.image_mime_type = None
    img.metadata.image_url = None
    codeflash_output = element_to_md(img)  # 12.5μs -> 9.60μs (29.7% faster)


def test_title_with_empty_text_returns_header_and_space():
    # A Title with empty string should still produce "# " as the function formats f"# {text}".
    t = Title("")  # empty text
    codeflash_output = element_to_md(t)  # 1.82μs -> 964ns (89.0% faster)


def test_large_scale_conversion_of_many_elements():
    # Create a large but bounded list of elements (below 1000 as required).
    # Alternate between Title and Image elements to exercise multiple branches repeatedly.
    elements = []
    n = 500  # large-scale but under 1000
    for i in range(n):
        if i % 2 == 0:
            # Titles with incremental text to ensure uniqueness of returned strings.
            elements.append(Title(f"Title {i}"))
        else:
            # Small base64 payload to keep memory usage low while testing base64 branch repeatedly.
            img = Image(f"Image {i}")
            img.metadata.image_base64 = "a"  # minimal base64-like payload
            img.metadata.image_mime_type = None  # triggers wildcard mime branch
            elements.append(img)

    # Convert all elements and validate expected patterns and counts.
    outputs = [element_to_md(e) for e in elements]

    # Verify every even index is a Title header and odd index is an image data URI.
    for i, out in enumerate(outputs):
        if i % 2 == 0:
            pass
        else:
            pass

from unstructured.documents.elements import ElementMetadata, Image, Table, Text, Title
from unstructured.staging.base import element_to_md


class TestElementToMdBasic:
    """Basic test cases for element_to_md function"""

    def test_title_element_with_text(self):
        """Test that Title elements are converted to markdown with # prefix"""
        title = Title(text="My Title")
        codeflash_output = element_to_md(title)
        result = codeflash_output  # 1.98μs -> 1.02μs (93.2% faster)

    def test_title_element_with_empty_text(self):
        """Test that Title elements with empty text still get # prefix"""
        title = Title(text="")
        codeflash_output = element_to_md(title)
        result = codeflash_output  # 1.82μs -> 987ns (84.6% faster)

    def test_title_element_with_special_characters(self):
        """Test that Title elements preserve special characters"""
        title = Title(text="Title with ## symbols & special chars!")
        codeflash_output = element_to_md(title)
        result = codeflash_output  # 1.88μs -> 1.03μs (82.5% faster)

    def test_table_with_html_metadata(self):
        """Test that Table elements with text_as_html return the HTML directly"""
        metadata = ElementMetadata(text_as_html="<table><tr><td>Cell</td></tr></table>")
        table = Table(text="Original text", metadata=metadata)
        codeflash_output = element_to_md(table)
        result = codeflash_output  # 3.59μs -> 2.69μs (33.3% faster)

    def test_table_without_html_metadata(self):
        """Test that Table elements without text_as_html fall back to element text"""
        table = Table(text="Table content without HTML")
        codeflash_output = element_to_md(table)
        result = codeflash_output  # 9.95μs -> 8.18μs (21.6% faster)

    def test_text_element_fallback(self):
        """Test that generic Text elements return their text unchanged"""
        text = Text(text="Plain text element")
        codeflash_output = element_to_md(text)
        result = codeflash_output  # 3.57μs -> 2.88μs (23.8% faster)

    def test_image_with_base64_and_no_mime_type_exclude_false(self):
        """Test Image with base64 data and no mime type (exclude_binary_image_data=False)"""
        metadata = ElementMetadata(image_base64="abc123def456", image_mime_type=None)
        image = Image(text="alt text", metadata=metadata)
        codeflash_output = element_to_md(image, exclude_binary_image_data=False)
        result = codeflash_output  # 10.1μs -> 9.30μs (8.23% faster)

    def test_image_with_base64_and_mime_type_exclude_false(self):
        """Test Image with base64 data and mime type (exclude_binary_image_data=False)"""
        metadata = ElementMetadata(image_base64="abc123def456", image_mime_type="image/png")
        image = Image(text="alt text", metadata=metadata)
        codeflash_output = element_to_md(image, exclude_binary_image_data=False)
        result = codeflash_output  # 5.19μs -> 3.80μs (36.4% faster)

    def test_image_with_url(self):
        """Test Image with image_url returns markdown link format"""
        metadata = ElementMetadata(image_url="https://example.com/image.png")
        image = Image(text="alt text", metadata=metadata)
        codeflash_output = element_to_md(image)
        result = codeflash_output  # 11.6μs -> 8.68μs (34.2% faster)

    def test_image_with_base64_exclude_binary_true(self):
        """Test that Image with base64 falls back to text when exclude_binary_image_data=True"""
        metadata = ElementMetadata(image_base64="abc123def456", image_mime_type="image/jpeg")
        image = Image(text="fallback text", metadata=metadata)
        codeflash_output = element_to_md(image, exclude_binary_image_data=True)
        result = codeflash_output  # 10.3μs -> 8.63μs (18.9% faster)

    def test_image_priority_url_over_base64(self):
        """Test that image_url is prioritized when checking match conditions"""
        metadata = ElementMetadata(
            image_base64="abc123def456",
            image_mime_type="image/png",
            image_url="https://example.com/image.png",
        )
        image = Image(text="alt text", metadata=metadata)
        codeflash_output = element_to_md(image)
        result = codeflash_output  # 4.85μs -> 3.49μs (38.9% faster)


class TestElementToMdEdgeCases:
    """Edge case test cases for element_to_md function"""

    def test_title_with_multiline_text(self):
        """Test Title with newline characters in text"""
        title = Title(text="Line 1\nLine 2")
        codeflash_output = element_to_md(title)
        result = codeflash_output  # 1.85μs -> 1.01μs (83.4% faster)

    def test_title_with_very_long_text(self):
        """Test Title with extremely long text content"""
        long_text = "A" * 10000
        title = Title(text=long_text)
        codeflash_output = element_to_md(title)
        result = codeflash_output  # 2.85μs -> 1.89μs (50.5% faster)

    def test_table_with_empty_html(self):
        """Test Table with empty string as text_as_html"""
        metadata = ElementMetadata(text_as_html="")
        table = Table(text="fallback text", metadata=metadata)
        codeflash_output = element_to_md(table)
        result = codeflash_output  # 3.35μs -> 2.47μs (35.3% faster)

    def test_table_with_complex_html(self):
        """Test Table with complex nested HTML structure"""
        html_content = "<table><thead><tr><th>Header</th></tr></thead><tbody><tr><td>Data</td></tr></tbody></table>"
        metadata = ElementMetadata(text_as_html=html_content)
        table = Table(text="ignored", metadata=metadata)
        codeflash_output = element_to_md(table)
        result = codeflash_output  # 3.26μs -> 2.48μs (31.4% faster)

    def test_image_with_empty_alt_text(self):
        """Test Image with empty alt text"""
        metadata = ElementMetadata(image_url="https://example.com/image.png")
        image = Image(text="", metadata=metadata)
        codeflash_output = element_to_md(image)
        result = codeflash_output  # 11.7μs -> 8.52μs (37.3% faster)

    def test_image_with_special_characters_in_alt_text(self):
        """Test Image with special characters in alt text"""
        metadata = ElementMetadata(image_url="https://example.com/image.png")
        image = Image(text="Image [with] (special) & chars!", metadata=metadata)
        codeflash_output = element_to_md(image)
        result = codeflash_output  # 11.5μs -> 8.43μs (35.8% faster)

    def test_image_with_url_containing_parameters(self):
        """Test Image with URL containing query parameters"""
        url = "https://example.com/image.png?size=large&format=png"
        metadata = ElementMetadata(image_url=url)
        image = Image(text="alt", metadata=metadata)
        codeflash_output = element_to_md(image)
        result = codeflash_output  # 11.6μs -> 8.67μs (33.8% faster)

    def test_image_base64_with_special_characters(self):
        """Test Image with base64 data containing special characters"""
        base64_data = "abc123+/==def456=="
        metadata = ElementMetadata(image_base64=base64_data, image_mime_type="image/png")
        image = Image(text="alt", metadata=metadata)
        codeflash_output = element_to_md(image, exclude_binary_image_data=False)
        result = codeflash_output  # 5.17μs -> 3.88μs (33.1% faster)

    def test_image_mime_type_with_charset(self):
        """Test Image with mime type containing additional parameters"""
        mime_type = "image/svg+xml;charset=utf-8"
        metadata = ElementMetadata(image_base64="abc123", image_mime_type=mime_type)
        image = Image(text="svg", metadata=metadata)
        codeflash_output = element_to_md(image, exclude_binary_image_data=False)
        result = codeflash_output  # 5.28μs -> 3.96μs (33.1% faster)

from unstructured.documents.elements import Element
from unstructured.staging.base import element_to_md


def test_element_to_md():
    element_to_md(
        Element(
            element_id="",
            coordinates=None,
            coordinate_system=None,
            metadata=None,
            detection_origin="",
        ),
        exclude_binary_image_data=True,
    )

🔎 Click to see Concolic Coverage Tests

Test File::Test Function	Original ⏱️	Optimized ⏱️	Speedup
codeflash_concolic_xdo_puqm/tmphjqmpzlo/test_concolic_coverage.py::test_element_to_md	4.66μs	3.80μs	22.7%✅

To edit these changes git checkout codeflash/optimize-element_to_md-mkrz8nli and push.