markitdown-wolfxl 0.1.0__py3-none-any.whl

markitdown_wolfxl/__init__.py

@@ -0,0 +1,65 @@
+"""Opt-in WolfXL XLSX conversion for MarkItDown's version-1 plugin interface."""
+
+from typing import Any, BinaryIO
+
+from markitdown import (
+    PRIORITY_SPECIFIC_FILE_FORMAT,
+    DocumentConverter,
+    DocumentConverterResult,
+    MarkItDown,
+    StreamInfo,
+)
+from markitdown.converters import HtmlConverter
+
+from ._reader import WolfxlReader
+
+__version__ = "0.1.0"
+__plugin_interface_version__ = 1
+
+__all__ = [
+    "__version__",
+    "__plugin_interface_version__",
+    "register_converters",
+    "WolfxlXlsxConverter",
+]
+
+
+def register_converters(markitdown: MarkItDown, **kwargs: Any) -> None:
+    """Register before the built-in XLSX converter, only when plugins are enabled."""
+    markitdown.register_converter(
+        WolfxlXlsxConverter(), priority=PRIORITY_SPECIFIC_FILE_FORMAT - 1
+    )
+
+
+class WolfxlXlsxConverter(DocumentConverter):
+    """Convert XLSX worksheet cell tables with WolfXL and public pandas APIs."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._html_converter = HtmlConverter()
+
+    def accepts(
+        self, file_stream: BinaryIO, stream_info: StreamInfo, **kwargs: Any
+    ) -> bool:
+        extension = (stream_info.extension or "").lower()
+        if extension:
+            return extension == ".xlsx"
+        return (stream_info.mimetype or "").lower() == (
+            "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+        )
+
+    def convert(
+        self, file_stream: BinaryIO, stream_info: StreamInfo, **kwargs: Any
+    ) -> DocumentConverterResult:
+        reader = WolfxlReader(file_stream)
+        try:
+            sheets = reader.parse()
+        finally:
+            reader.close()
+        fragments = []
+        for name, frame in sheets.items():
+            markdown = self._html_converter.convert_string(
+                frame.to_html(index=False), **kwargs
+            ).markdown.strip()
+            fragments.append(f"## {name}\n{markdown}")
+        return DocumentConverterResult(markdown="\n\n".join(fragments).strip())

markitdown_wolfxl/_reader.py

@@ -0,0 +1,148 @@
+"""Opt-in XLSX loading using only public WolfXL and pandas APIs."""
+
+from typing import Any
+
+import pandas as pd
+from wolfxl import load_workbook
+
+_NAN = float("nan")
+
+# pandas' documented default missing-value spellings for read_excel/read_csv.
+_NA_VALUES = {
+    "",
+    "#N/A",
+    "#N/A N/A",
+    "#NA",
+    "-1.#IND",
+    "-1.#QNAN",
+    "-NaN",
+    "-nan",
+    "1.#IND",
+    "1.#QNAN",
+    "<NA>",
+    "N/A",
+    "NA",
+    "NULL",
+    "NaN",
+    "None",
+    "n/a",
+    "nan",
+    "null",
+}
+
+
+def _cell_value(cell: Any) -> Any:
+    value = cell.value
+    if value is None:
+        return ""
+    if cell.data_type == "e":
+        return _NAN
+    if cell.data_type == "n" and isinstance(value, (int, float)):
+        integer = int(value)
+        return integer if integer == value else float(value)
+    return value
+
+
+def _frame(rows: list[list[Any]]) -> pd.DataFrame:
+    # Ignore trailing empty rows/cells, but retain interior blanks and sheet order.
+    while rows and not rows[-1]:
+        rows.pop()
+    if not rows:
+        return pd.DataFrame()
+    width = max(map(len, rows))
+    rows = [row + [""] * (width - len(row)) for row in rows]
+    names = [
+        value if value != "" else f"Unnamed: {i}" for i, value in enumerate(rows[0])
+    ]
+    # Match the default header=0 naming, including collisions with literal suffixes.
+    counts: dict[Any, int] = {}
+    order = [i for i, value in enumerate(rows[0]) if value != ""] + [
+        i for i, value in enumerate(rows[0]) if value == ""
+    ]
+    for i in order:
+        name = names[i]
+        count = counts.get(name, 0)
+        while count:
+            counts[name] = count + 1
+            candidate = f"{name}.{count}"
+            if candidate not in names:
+                name = candidate
+            count = counts.get(name, 0)
+        names[i] = name
+        counts[name] = count + 1
+    if len(rows) == 1:
+        return pd.DataFrame(columns=names)
+    columns = []
+    for i in range(width):
+        raw_values = [row[i] for row in rows[1:]]
+        values = [
+            _NAN if isinstance(value, str) and value in _NA_VALUES else value
+            for value in raw_values
+        ]
+        series = pd.Series(values, dtype=object)
+        if series.isna().any():
+            try:
+                nonmissing_numeric = pd.to_numeric(series.dropna())
+            except (ValueError, TypeError):
+                pass
+            else:
+                # read_excel retains object values, including NA spellings, when
+                # unsigned 64-bit integers and missing values cannot share a
+                # lossless NumPy dtype. Do not round those integers to float.
+                if pd.api.types.is_unsigned_integer_dtype(nonmissing_numeric.dtype):
+                    columns.append(pd.Series(raw_values, dtype=object))
+                    continue
+        try:
+            series = pd.to_numeric(series)
+        except (ValueError, TypeError):
+            # Object columns retain the first equal scalar, including Python's
+            # 1 == True / 0 == False aliases, just as read_excel does.
+            canonical: dict[Any, Any] = {}
+            for value in series:
+                canonical.setdefault(value, value)
+            series = series.map(canonical)
+            # Numeric inference precedes boolean inference, as in read_excel.
+            nonmissing = series.dropna()
+            boolean_values = {
+                True: True,
+                False: False,
+                "True": True,
+                "TRUE": True,
+                "true": True,
+                "False": False,
+                "FALSE": False,
+                "false": False,
+            }
+            if len(nonmissing) and all(
+                isinstance(value, (str, bool)) and value in boolean_values
+                for value in nonmissing
+            ):
+                series = series.map(boolean_values)
+        columns.append(series.infer_objects())
+    frame = pd.concat(columns, axis=1)
+    frame.columns = names
+    return frame
+
+
+class WolfxlReader:
+    def __init__(self, filepath_or_buffer: Any) -> None:
+        self.book = load_workbook(
+            filepath_or_buffer, read_only=True, data_only=True, keep_links=False
+        )
+
+    def parse(self, sheet_name: None = None) -> dict[str, pd.DataFrame]:
+        sheets = {}
+        for sheet in self.book.worksheets:
+            # Producer dimension hints can understate the actual XML data.
+            sheet.reset_dimensions()
+            rows = []
+            for row in sheet.iter_rows():
+                values = [_cell_value(cell) for cell in row]
+                while values and values[-1] == "":
+                    values.pop()
+                rows.append(values)
+            sheets[sheet.title] = _frame(rows)
+        return sheets
+
+    def close(self) -> None:
+        self.book.close()

markitdown_wolfxl-0.1.0.dist-info/METADATA

@@ -0,0 +1,75 @@
+Metadata-Version: 2.5
+Name: markitdown-wolfxl
+Version: 0.1.0
+Summary: An opt-in WolfXL XLSX converter plugin for MarkItDown
+Project-URL: Repository, https://github.com/SynthGL/markitdown-wolfxl
+Project-URL: Issues, https://github.com/SynthGL/markitdown-wolfxl/issues
+Author: Wolfgang Schoenberger
+License-Expression: MIT
+License-File: LICENSE
+Keywords: excel,markdown,markitdown,markitdown-plugin,wolfxl,xlsx
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.10
+Requires-Dist: markitdown<0.2,>=0.1.9
+Requires-Dist: pandas<3,>=2.2
+Requires-Dist: wolfxl<2.1,>=2.0.17
+Provides-Extra: test
+Requires-Dist: openpyxl<4,>=3.1; extra == 'test'
+Requires-Dist: pytest; extra == 'test'
+Description-Content-Type: text/markdown
+
+# markitdown-wolfxl
+
+A third-party, opt-in XLSX converter plugin for [MarkItDown](https://github.com/microsoft/markitdown) that reads workbooks with [WolfXL](https://github.com/SynthGL/wolfxl-oss). It uses only WolfXL's public workbook API and public pandas constructors. It does not modify MarkItDown, register a pandas engine, or import private pandas modules.
+
+## Install
+
+```sh
+pip install markitdown-wolfxl
+markitdown --list-plugins
+```
+
+The package requires `wolfxl>=2.0.17,<2.1`, pandas 2.x, and MarkItDown `>=0.1.9,<0.2`. WolfXL ships native wheels for common platforms; see its project page for the current list.
+
+## Explicit activation
+
+Installing the package does not change ordinary MarkItDown conversions, because MarkItDown keeps plugins disabled by default. Enable plugins to use it:
+
+```python
+from markitdown import MarkItDown
+
+result = MarkItDown(enable_plugins=True).convert("workbook.xlsx")
+print(result.markdown)
+```
+
+```sh
+markitdown --use-plugins workbook.xlsx
+```
+
+The package follows MarkItDown's version-1 plugin interface: entry point group `markitdown.plugin`, `__plugin_interface_version__ = 1`, and `register_converters`. Its XLSX converter is registered at priority `PRIORITY_SPECIFIC_FILE_FORMAT - 1`, ahead of the built-in converter. Files with an explicit non-XLSX extension, including `.xls`, are declined. XLSX MIME information can identify streams without a filename. Other enabled plugins remain subject to MarkItDown's normal priority rules.
+
+## Output and limitations
+
+Each worksheet becomes a Markdown heading and a cell table, in workbook order, using first-row headers, pandas-compatible missing values and dtype inference, and MarkItDown's public HTML converter. Workbooks are closed on success and on conversion failure. The reader ignores understated worksheet-dimension hints instead of silently truncating data.
+
+This converter handles worksheet cell content, not embedded-image OCR or custom image hooks. Do not enable it when another XLSX plugin's image processing is required. Malformed ZIP or XML, encrypted, Strict OOXML, and some legacy-producer files can convert differently from the built-in reader. WolfXL's rejection of duplicate ZIP entry names is kept.
+
+When this plugin raises an ordinary exception, MarkItDown may fall back to another converter, so a successful MarkItDown result does not by itself show that WolfXL converted the file. For example, WolfXL rejects a workbook with a case-insensitive duplicate ZIP entry, and MarkItDown's built-in reader then accepts it. Enabling this plugin is **not an application-wide ZIP validation policy or security boundary**.
+
+On a 353-file XLSX test corpus, 318 files that WolfXL converts produce Markdown byte-identical to MarkItDown's built-in converter. No performance claim is made.
+
+## Tests
+
+```sh
+pip install -e '.[test]'
+pytest
+```
+
+Tests cover entry-point discovery, explicit activation, registration priority, XLSX-only acceptance, public-API dispatch, headers and type inference, dimension hints, workbook closure, and fallback behavior.
+
+## License
+
+MIT. This is an independent third-party plugin, not sponsored by or affiliated with Microsoft. MarkItDown's copyright notice is retained in `LICENSE` for the adapted table-to-Markdown assembly.

markitdown_wolfxl-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+markitdown_wolfxl/__init__.py,sha256=QPCOnyFNy4z0QIivcjhrIn5ma0LNLjc3XKf7Zahk88A,2021
+markitdown_wolfxl/_reader.py,sha256=Q4DmQeF5Fy0yNDGz3RM3eSHHbKMjTJn9LhHg3Hnu6EE,4828
+markitdown_wolfxl-0.1.0.dist-info/METADATA,sha256=47NAcAi75Xz-8OBRIqQi-u2MEmK9BUyVYS5Ayu4eq24,4164
+markitdown_wolfxl-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+markitdown_wolfxl-0.1.0.dist-info/entry_points.txt,sha256=Y-JB7M9IAXTEc2-dj05DU1rwYlM4FwXs_E353glvJIM,47
+markitdown_wolfxl-0.1.0.dist-info/licenses/LICENSE,sha256=uro6BVddWkWb1qAUszidHnkfUWONBf6kL1zXq_0KlxA,1115
+markitdown_wolfxl-0.1.0.dist-info/RECORD,,

markitdown_wolfxl-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

markitdown_wolfxl-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[markitdown.plugin]
+wolfxl = markitdown_wolfxl

markitdown_wolfxl-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Wolfgang Schoenberger
+Copyright (c) Microsoft Corporation.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.