Python tool for converting files and office documents to Markdown.
fix: handle DOCX files with inconsistent ZIP filename casing (#1812) (#2016)
liyrdsa5ddc8efd557
diff --git a/packages/markitdown-ocr/src/markitdown_ocr/_docx_converter_with_ocr.py b/packages/markitdown-ocr/src/markitdown_ocr/_docx_converter_with_ocr.pyindex 9fd3b07e..f0201689 100644--- a/packages/markitdown-ocr/src/markitdown_ocr/_docx_converter_with_ocr.py+++ b/packages/markitdown-ocr/src/markitdown_ocr/_docx_converter_with_ocr.py@@ -94,9 +94,16 @@ class DocxConverterWithOCR(HtmlConverter):kwargs.get("ocr_service") or self.ocr_service)+ # Pre-process once, up front, so that every subsequent read sees the+ # repaired archive. pre_process_docx() also fixes .docx files whose ZIP+ # local file headers disagree with the central directory; reading the+ # original stream first would make those raise, or silently yield no+ # images and drop the OCR output.+ pre_process_stream = pre_process_docx(file_stream)+# Read the embedded style map and combine with any provided style mapcaller_style_map = kwargs.get("style_map")- embedded_style_map = _read_embedded_style_map(file_stream)+ embedded_style_map = _read_embedded_style_map(pre_process_stream)style_map = "\n".join(part@@ -110,12 +117,13 @@ class DocxConverterWithOCR(HtmlConverter):if ocr_service:# 1. Extract and OCR images — returns raw text per image- file_stream.seek(0)- image_ocr_map = self._extract_and_ocr_images(file_stream, ocr_service)+ pre_process_stream.seek(0)+ image_ocr_map = self._extract_and_ocr_images(+ pre_process_stream, ocr_service+ )# 2. Convert DOCX → HTML via mammoth- file_stream.seek(0)- pre_process_stream = pre_process_docx(file_stream)+ pre_process_stream.seek(0)html_result = mammoth.convert_to_html(pre_process_stream,style_map=style_map,@@ -144,7 +152,7 @@ class DocxConverterWithOCR(HtmlConverter):return DocumentConverterResult(markdown=md)else:# Standard conversion without OCR- pre_process_stream = pre_process_docx(file_stream)+ pre_process_stream.seek(0)return self._html_converter.convert_string(mammoth.convert_to_html(pre_process_stream,diff --git a/packages/markitdown-ocr/tests/test_docx_converter.py b/packages/markitdown-ocr/tests/test_docx_converter.pyindex fcd0944b..2538206d 100644--- a/packages/markitdown-ocr/tests/test_docx_converter.py+++ b/packages/markitdown-ocr/tests/test_docx_converter.py@@ -10,6 +10,8 @@ OCR block format used by the converter:[End OCR]*"""+import io+import structimport sysimport zipfilefrom pathlib import Path@@ -279,3 +281,59 @@ def test_docx_underlined_text_is_preserved_with_ocr(f, StreamInfo(extension=".docx"), ocr_service=svc).markdownassert "plain <u>underlined</u>" in md+++# ---------------------------------------------------------------------------+# ZIP local file header casing mismatch+# ---------------------------------------------------------------------------+++def _uppercase_local_header_names(docx_bytes: bytes) -> bytes:+ """Uppercase every local file header filename, leaving the central directory+ untouched, to mimic generators that disagree with themselves about casing."""+ raw = bytearray(docx_bytes)+ offset = patched = 0+ while offset + 30 <= len(raw) and raw[offset : offset + 4] == b"PK\x03\x04":+ fname_len = struct.unpack_from("<H", raw, offset + 26)[0]+ extra_len = struct.unpack_from("<H", raw, offset + 28)[0]+ comp_size = struct.unpack_from("<I", raw, offset + 18)[0]+ name = raw[offset + 30 : offset + 30 + fname_len]+ if name.upper() != name:+ raw[offset + 30 : offset + 30 + fname_len] = name.upper()+ patched += 1+ offset += 30 + fname_len + extra_len + comp_size+ assert patched, "fixture produced no mismatched local file headers"+ return bytes(raw)+++def test_docx_zip_filename_casing_mismatch_preserves_ocr(svc: MockOCRService) -> None:+ """OCR output survives a .docx whose local file headers disagree with the+ central directory on casing.++ The image extraction swallows every exception, so an unrepaired stream used+ to yield an empty OCR map and silently drop the OCR blocks rather than fail.+ """+ path = TEST_DATA_DIR / "docx_image_middle.docx"+ if not path.exists():+ pytest.skip(f"Test file not found: {path}")++ original = path.read_bytes()+ mismatched = _uppercase_local_header_names(original)++ # Plain zipfile cannot read the mismatched archive ...+ with pytest.raises(zipfile.BadZipFile):+ with zipfile.ZipFile(io.BytesIO(mismatched), "r") as zf:+ for name in zf.namelist():+ zf.read(name)++ # ... but the converter produces the same output it does for the original.+ converter = DocxConverterWithOCR()+ expected = converter.convert(+ io.BytesIO(original), StreamInfo(extension=".docx"), ocr_service=svc+ ).markdown+ actual = converter.convert(+ io.BytesIO(mismatched), StreamInfo(extension=".docx"), ocr_service=svc+ ).markdown++ assert _MOCK_TEXT in actual+ assert actual == expecteddiff --git a/packages/markitdown/src/markitdown/converter_utils/docx/pre_process.py b/packages/markitdown/src/markitdown/converter_utils/docx/pre_process.pyindex ee5da4e6..e569c0f2 100644--- a/packages/markitdown/src/markitdown/converter_utils/docx/pre_process.py+++ b/packages/markitdown/src/markitdown/converter_utils/docx/pre_process.py@@ -1,3 +1,4 @@+import structimport zipfilefrom io import BytesIOfrom typing import BinaryIO@@ -138,6 +139,66 @@ def _pre_process_math(content: bytes) -> bytes:return str(soup).encode()+def _fix_zip_filename_casing(input_docx: BinaryIO) -> BinaryIO:+ """+ Fix ZIP files where local file header filenames differ in casing+ from the central directory filenames.++ Some document generators (e.g. certain Microsoft Word versions,+ legal document systems) produce .docx/.pptx files where the central+ directory records one casing (e.g. 'customXml/item2.xml') but+ the local file headers record another (e.g. 'customXML/item2.xml').+ Python's zipfile module raises BadZipFile when reading such files.++ This function patches local file header filenames to match the+ central directory, which is the authoritative source used by+ zipfile.ZipFile.+ """+ input_docx.seek(0)+ raw = bytearray(input_docx.read())++ # Read the central directory to get authoritative filenames+ try:+ with zipfile.ZipFile(BytesIO(raw), "r") as zf:+ cd_entries = {+ zi.header_offset: (zi.orig_filename, zi.flag_bits)+ for zi in zf.infolist()+ }+ except zipfile.BadZipFile:+ # Can't even read central directory — return as-is, let it fail later+ input_docx.seek(0)+ return input_docx++ patched = False+ for offset, (cd_name, flag_bits) in cd_entries.items():+ # Verify local file header signature+ if offset + 30 > len(raw) or raw[offset : offset + 4] != b"PK\x03\x04":+ continue++ local_fname_len = struct.unpack_from("<H", raw, offset + 26)[0]+ if offset + 30 + local_fname_len > len(raw):+ continue++ local_name = bytes(raw[offset + 30 : offset + 30 + local_fname_len])+ # ZIP filenames are cp437 unless flag bit 11 marks them as UTF-8, which is+ # how zipfile decoded orig_filename in the first place.+ central_name = cd_name.encode("utf-8" if flag_bits & 0x800 else "cp437")++ # Only patch if lengths match but content differs (casing mismatch)+ if (+ local_name != central_name+ and len(local_name) == len(central_name)+ and local_name.lower() == central_name.lower()+ ):+ raw[offset + 30 : offset + 30 + local_fname_len] = central_name+ patched = True++ if patched:+ return BytesIO(bytes(raw))+ input_docx.seek(0)+ return input_docx++def _pre_process_styles(content: bytes) -> bytes:"""Repairs DOCX style definitions that Mammoth cannot read.@@ -175,6 +236,9 @@ def pre_process_docx(input_docx: BinaryIO) -> BinaryIO:Returns:BinaryIO: A binary output stream representing the processed DOCX file."""+ # Fix ZIP filename casing mismatch before any processing+ input_docx = _fix_zip_filename_casing(input_docx)+output_docx = BytesIO()# The pre-processing steps to apply to each file in the .docxpre_process_enable_files = {diff --git a/packages/markitdown/tests/test_module_misc.py b/packages/markitdown/tests/test_module_misc.pyindex 22df3aad..2fa52f71 100644--- a/packages/markitdown/tests/test_module_misc.py+++ b/packages/markitdown/tests/test_module_misc.py@@ -479,6 +479,134 @@ def test_docx_equations() -> None:assert block_equations, "No block equations found in the document."+def test_docx_zip_filename_casing_mismatch() -> None:+ """Test that DOCX files with inconsistent ZIP filename casing are handled.++ Some document generators produce .docx files where the central directory+ records one casing (e.g. 'word/document.xml') but the local file headers+ record another (e.g. 'Word/Document.XML'). Python's zipfile module raises+ BadZipFile when reading such files. This test verifies that MarkItDown+ handles this gracefully.++ See: https://github.com/microsoft/markitdown/issues/1812+ """+ import struct++ markitdown = MarkItDown()+ docx_file = os.path.join(TEST_FILES_DIR, "test.docx")++ # Read the original docx and get its expected content+ original_result = markitdown.convert(docx_file)+ assert original_result.markdown.strip(), "Original DOCX should have content"++ # Read raw bytes and corrupt the local file header filenames+ with open(docx_file, "rb") as f:+ raw = bytearray(f.read())++ # Find all local file headers and uppercase their filenames+ corrupted = bytearray(raw)+ offset = 0+ patched_count = 0+ while offset + 30 <= len(corrupted):+ if corrupted[offset : offset + 4] != b"PK\x03\x04":+ break+ fname_len = struct.unpack_from("<H", corrupted, offset + 26)[0]+ extra_len = struct.unpack_from("<H", corrupted, offset + 28)[0]+ if offset + 30 + fname_len > len(corrupted):+ break+ # Uppercase the filename in the local header+ old_name = corrupted[offset + 30 : offset + 30 + fname_len]+ new_name = old_name.upper()+ if old_name != new_name:+ corrupted[offset + 30 : offset + 30 + fname_len] = new_name+ patched_count += 1+ comp_size = struct.unpack_from("<I", corrupted, offset + 18)[0]+ offset = offset + 30 + fname_len + extra_len + comp_size++ assert patched_count > 0, "Should have patched at least one local file header"++ # Verify the corrupted file would fail with plain zipfile+ with pytest.raises(zipfile.BadZipFile):+ with zipfile.ZipFile(io.BytesIO(bytes(corrupted)), "r") as zf:+ for name in zf.namelist():+ zf.read(name)++ # Verify MarkItDown can still convert it+ corrupted_result = markitdown.convert_stream(+ io.BytesIO(bytes(corrupted)),+ file_extension=".docx",+ )+ assert (+ corrupted_result.markdown.strip()+ ), "Corrupted DOCX should still produce content"+ # Content should be equivalent to the original+ assert (+ original_result.markdown.strip() == corrupted_result.markdown.strip()+ ), "Corrupted DOCX should produce the same output as original"+++def test_docx_zip_filename_non_casing_mismatch_still_rejected() -> None:+ """Only case-only local/central filename disagreements are repaired.++ Equal encoded length does not imply two names differ only in case, so the+ repair must not be used to wave through archives whose local and central+ directory names genuinely disagree -- zipfile rejects those for good+ reason, and honouring that keeps the workaround scoped to issue #1812.+ """+ import struct++ from markitdown.converter_utils.docx.pre_process import (+ _fix_zip_filename_casing,+ )++ def build_zip(first_name: str) -> bytes:+ buf = io.BytesIO()+ with zipfile.ZipFile(buf, "w") as zf:+ zf.writestr(first_name, b"payload-a")+ zf.writestr("word/document.xml", b"payload-b")+ return buf.getvalue()++ def replace_first_local_name(data: bytes, new_name: bytes) -> bytes:+ """Rewrite only the first local file header's name, leaving the central+ directory -- the authoritative copy -- untouched."""+ raw = bytearray(data)+ fname_len = struct.unpack_from("<H", raw, 26)[0]+ assert len(new_name) == fname_len, "mutation must preserve the length"+ raw[30 : 30 + fname_len] = new_name+ return bytes(raw)++ def reads_cleanly(data: bytes) -> bool:+ try:+ with zipfile.ZipFile(io.BytesIO(data), "r") as zf:+ for name in zf.namelist():+ zf.read(name)+ except zipfile.BadZipFile:+ return False+ return True++ original = "[Content_Types].xml"++ # A case-only mismatch is repaired ...+ case_only = replace_first_local_name(build_zip(original), original.upper().encode())+ assert not reads_cleanly(case_only)+ repaired = _fix_zip_filename_casing(io.BytesIO(case_only))+ assert reads_cleanly(repaired.read())++ # ... but an equal-length mismatch that is not case-only is left alone,+ # so zipfile still refuses the archive.+ for mutated_name in (+ b"ZBnoudou^Uxqdr\\/ylm", # unrelated, same length+ b"[Content_Types].xmy", # a single differing character+ b"[content_types]/xml", # differs only outside the cased characters+ ):+ data = replace_first_local_name(build_zip(original), mutated_name)+ assert not reads_cleanly(data), f"{mutated_name!r} should not be readable"+ result = _fix_zip_filename_casing(io.BytesIO(data))+ assert not reads_cleanly(+ result.read()+ ), f"{mutated_name!r} must not be silently repaired"++def test_docx_malformed_equations() -> None:"""Malformed equations should not crash the converter (issue #1979)."""import zipfile@@ -1478,6 +1606,8 @@ if __name__ == "__main__":test_data_uris,test_file_uris,test_docx_comments,+ test_docx_zip_filename_casing_mismatch,+ test_docx_zip_filename_non_casing_mismatch_still_rejected,test_input_as_strings,test_markitdown_remote,test_speech_transcription,