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.
