feat: preserve Excel cell formatting via XlsxConfig (fix #53)

Author: Vanity-1

packages/markitdown/src/markitdown/__init__.py

@@ -17,6 +17,7 @@
     FileConversionException,
     UnsupportedFormatException,
 )
+from .converters._xlsx_converter import XlsxConfig
 
 __all__ = [
     "__version__",
@@ -29,6 +30,7 @@
     "FileConversionException",
     "UnsupportedFormatException",
     "StreamInfo",
+    "XlsxConfig",
     "PRIORITY_SPECIFIC_FILE_FORMAT",
     "PRIORITY_GENERIC_FILE_FORMAT",
 ]

packages/markitdown/src/markitdown/_markitdown.py

@@ -193,7 +193,9 @@ def enable_builtins(self, **kwargs) -> None:
             self.register_converter(YouTubeConverter())
             self.register_converter(BingSerpConverter())
             self.register_converter(DocxConverter())
-            self.register_converter(XlsxConverter())
+            self.register_converter(
+                XlsxConverter(config=kwargs.get("xlsx_config"))
+            )
             self.register_converter(XlsConverter())
             self.register_converter(PptxConverter())
             self.register_converter(AudioConverter())

packages/markitdown/src/markitdown/converters/_xlsx_converter.py

@@ -1,5 +1,8 @@
+import re
 import sys
-from typing import BinaryIO, Any
+from dataclasses import dataclass
+from datetime import datetime
+from typing import BinaryIO, Any, Optional
 from ._html_converter import HtmlConverter
 from .._base_converter import DocumentConverter, DocumentConverterResult
 from .._exceptions import MissingDependencyException, MISSING_DEPENDENCY_MESSAGE
@@ -33,14 +36,29 @@
 ACCEPTED_XLS_FILE_EXTENSIONS = [".xls"]
 
 
+@dataclass
+class XlsxConfig:
+    """Configuration options for :class:`XlsxConverter`.
+
+    Attributes:
+        preserve_formatting: When ``True``, cell number formats (currency,
+            percentage, thousands separators, dates, etc.) are preserved in the
+            Markdown output. Defaults to ``False`` to keep the existing behavior
+            of emitting raw cell values.
+    """
+
+    preserve_formatting: bool = False
+
+
 class XlsxConverter(DocumentConverter):
     """
     Converts XLSX files to Markdown, with each sheet presented as a separate Markdown table.
     """
 
-    def __init__(self):
+    def __init__(self, config: Optional[XlsxConfig] = None):
         super().__init__()
         self._html_converter = HtmlConverter()
+        self._config = config or XlsxConfig()
 
     def accepts(
         self,
@@ -80,6 +98,9 @@ def convert(
                 _xlsx_dependency_exc_info[2]
             )
 
+        if self._config.preserve_formatting:
+            return self._convert_with_formatting(file_stream, **kwargs)
+
         sheets = pd.read_excel(file_stream, sheet_name=None, engine="openpyxl")
         md_content = ""
         for s in sheets:
@@ -94,6 +115,146 @@ def convert(
 
         return DocumentConverterResult(markdown=md_content.strip())
 
+    def _convert_with_formatting(
+        self,
+        file_stream: BinaryIO,
+        **kwargs: Any,
+    ) -> DocumentConverterResult:
+        """Convert an XLSX file to Markdown while preserving cell number formats."""
+        wb = openpyxl.load_workbook(file_stream, data_only=True)
+        md_content = ""
+        for sheet_name in wb.sheetnames:
+            sheet = wb[sheet_name]
+            if sheet.max_row is None or sheet.max_column is None:
+                continue
+
+            md_content += f"## {sheet_name}\n"
+            data = [
+                [self._format_cell_value(cell) for cell in row]
+                for row in sheet.iter_rows()
+            ]
+            if not data:
+                continue
+
+            df = pd.DataFrame(data)
+            # Use the first row as the header, matching pandas.read_excel defaults
+            header = [
+                str(c) if c is not None and c != "" else f"Unnamed: {i}"
+                for i, c in enumerate(df.iloc[0])
+            ]
+            df = df.iloc[1:]
+            df.columns = header
+            html_content = df.to_html(index=False)
+            md_content += (
+                self._html_converter.convert_string(
+                    html_content, **kwargs
+                ).markdown.strip()
+                + "\n\n"
+            )
+
+        return DocumentConverterResult(markdown=md_content.strip())
+
+    def _format_cell_value(self, cell) -> str:
+        """Render a cell value using its Excel number format."""
+        value = cell.value
+        if value is None:
+            return ""
+        if isinstance(value, bool):
+            return str(value)
+        if isinstance(value, datetime):
+            return self._format_datetime(value, cell.number_format)
+        if not isinstance(value, (int, float)):
+            return str(value)
+
+        number_format = cell.number_format
+        if not number_format or number_format == "General":
+            return str(value)
+
+        if "%" in number_format:
+            return self._format_percentage(value, number_format)
+
+        currency_symbol = self._extract_currency_symbol(number_format)
+        if currency_symbol is not None:
+            return self._format_currency(value, number_format, currency_symbol)
+
+        if "#,##" in number_format or re.search(r"0+\.0+", number_format):
+            return self._format_number(value, number_format)
+
+        return str(value)
+
+    def _extract_currency_symbol(self, number_format: str) -> Optional[str]:
+        """Return the currency symbol embedded in an Excel number format, if any."""
+        # Quoted literal, e.g. "$"#,##0.00 or #,##0.00"€"
+        for match in re.finditer(r'"([^"]*)"', number_format):
+            symbol = match.group(1).strip()
+            if symbol and not symbol.replace(".", "").isdigit():
+                return symbol
+        # Currency code, e.g. [$USD] or [$¥-411]
+        for match in re.finditer(r"\[\$([^\]]*)\]", number_format):
+            code = re.sub(r"-\d+$", "", match.group(1)).strip()
+            if code:
+                return code
+        return None
+
+    def _format_number(self, value, number_format: str) -> str:
+        decimal_places = self._decimal_places(number_format)
+        if "#,##" in number_format:
+            return f"{value:,.{decimal_places}f}"
+        return f"{value:.{decimal_places}f}"
+
+    def _format_percentage(self, value, number_format: str) -> str:
+        decimal_places = self._decimal_places(number_format)
+        return f"{value * 100:.{decimal_places}f}%"
+
+    def _format_currency(
+        self, value, number_format: str, symbol: str
+    ) -> str:
+        decimal_places = self._decimal_places(number_format)
+        if "#,##" in number_format:
+            formatted = f"{value:,.{decimal_places}f}"
+        else:
+            formatted = f"{value:.{decimal_places}f}"
+
+        # Place the symbol before or after the number to match the format
+        num_pos = len(number_format)
+        for ch in "0#":
+            idx = number_format.find(ch)
+            if idx != -1:
+                num_pos = min(num_pos, idx)
+        symbol_pos = number_format.find(symbol)
+        prefix = symbol_pos != -1 and symbol_pos < num_pos
+
+        if value < 0:
+            abs_formatted = formatted[1:]
+            if "(" in number_format:
+                return f"({symbol}{abs_formatted})"
+            return (
+                f"-{symbol}{abs_formatted}"
+                if prefix
+                else f"-{abs_formatted}{symbol}"
+            )
+        return f"{symbol}{formatted}" if prefix else f"{formatted}{symbol}"
+
+    def _decimal_places(self, number_format: str) -> int:
+        """Count the digit placeholders after the decimal point in a format."""
+        if "." not in number_format:
+            return 0
+        decimal_places = 0
+        for ch in number_format.split(".", 1)[1]:
+            if ch == "0":
+                decimal_places += 1
+            elif ch in "#?":
+                continue
+            else:
+                break
+        return decimal_places
+
+    def _format_datetime(self, value: datetime, number_format: str) -> str:
+        fmt = number_format.lower()
+        if any(tok in fmt for tok in ("hh", "h:", "am/pm")):
+            return value.strftime("%Y-%m-%d %H:%M")
+        return value.strftime("%Y-%m-%d")
+
 
 class XlsConverter(DocumentConverter):
     """

packages/markitdown/tests/test_xlsx_converter.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3 -m pytest
+import io
+
+import pytest
+from openpyxl import Workbook
+
+from markitdown import MarkItDown, XlsxConfig
+
+
+def _convert(data: bytes, *, preserve_formatting: bool = False) -> str:
+    md = MarkItDown(
+        xlsx_config=XlsxConfig(preserve_formatting=preserve_formatting)
+    )
+    return md.convert(io.BytesIO(data), file_extension=".xlsx").text_content
+
+
+def test_xlsx_default_does_not_preserve_formatting() -> None:
+    wb = Workbook()
+    ws = wb.active
+    ws.title = "Sheet1"
+    ws.append(["Item", "Cost"])
+    ws.append(["Breakfast", 5])
+    ws.cell(row=2, column=2).number_format = '"$"#,##0.00'
+    buf = io.BytesIO()
+    wb.save(buf)
+
+    result = _convert(buf.getvalue())
+    assert "5" in result
+    assert "$" not in result
+
+
+def test_xlsx_preserve_currency() -> None:
+    wb = Workbook()
+    ws = wb.active
+    ws.title = "Sheet1"
+    ws.append(["Item", "Cost", "Total"])
+    ws.append(["Breakfast", 5, 100])
+    ws.append(["Laptops", 1199, 5995])
+    for row in (2, 3):
+        ws.cell(row=row, column=2).number_format = '"$"#,##0.00'
+        ws.cell(row=row, column=3).number_format = '"$"#,##0.00'
+    buf = io.BytesIO()
+    wb.save(buf)
+
+    result = _convert(buf.getvalue(), preserve_formatting=True)
+    assert "$5.00" in result
+    assert "$100.00" in result
+    assert "$1,199.00" in result
+    assert "$5,995.00" in result
+
+
+def test_xlsx_preserve_percentage() -> None:
+    wb = Workbook()
+    ws = wb.active
+    ws.title = "Sheet1"
+    ws.append(["Name", "Rate"])
+    ws.append(["A", 0.255])
+    ws.cell(row=2, column=2).number_format = "0.0%"
+    buf = io.BytesIO()
+    wb.save(buf)
+
+    result = _convert(buf.getvalue(), preserve_formatting=True)
+    assert "25.5%" in result
+
+
+def test_xlsx_preserve_thousands_separator() -> None:
+    wb = Workbook()
+    ws = wb.active
+    ws.title = "Sheet1"
+    ws.append(["Name", "Qty"])
+    ws.append(["A", 1234567])
+    ws.cell(row=2, column=2).number_format = "#,##0"
+    buf = io.BytesIO()
+    wb.save(buf)
+
+    result = _convert(buf.getvalue(), preserve_formatting=True)
+    assert "1,234,567" in result
+
+
+def test_xlsx_preserve_other_currency_symbol() -> None:
+    wb = Workbook()
+    ws = wb.active
+    ws.title = "Sheet1"
+    ws.append(["Name", "Price"])
+    ws.append(["A", 9.5])
+    ws.cell(row=2, column=2).number_format = '"€"#,##0.00'
+    buf = io.BytesIO()
+    wb.save(buf)
+
+    result = _convert(buf.getvalue(), preserve_formatting=True)
+    assert "€9.50" in result
+
+
+def test_xlsx_preserve_negative_currency() -> None:
+    wb = Workbook()
+    ws = wb.active
+    ws.title = "Sheet1"
+    ws.append(["Name", "Balance"])
+    ws.append(["A", -1234.5])
+    ws.cell(row=2, column=2).number_format = '"$"#,##0.00'
+    buf = io.BytesIO()
+    wb.save(buf)
+
+    result = _convert(buf.getvalue(), preserve_formatting=True)
+    assert "-$1,234.50" in result
+
+
+def test_xlsx_preserve_dates() -> None:
+    from datetime import datetime
+
+    wb = Workbook()
+    ws = wb.active
+    ws.title = "Sheet1"
+    ws.append(["Name", "Date"])
+    ws.append(["A", datetime(2024, 1, 15)])
+    ws.cell(row=2, column=2).number_format = "yyyy-mm-dd"
+    buf = io.BytesIO()
+    wb.save(buf)
+
+    result = _convert(buf.getvalue(), preserve_formatting=True)
+    assert "2024-01-15" in result
+
+
+def test_xlsx_config_exported() -> None:
+    assert XlsxConfig(preserve_formatting=True).preserve_formatting is True
+    assert XlsxConfig().preserve_formatting is False