lxml XML Declaration Fix for docx Files

Problem (2026-07-01, 劳务派遣协议案)

When lxml serializes XML (via etree.tostring() or python-docx's Document.save()), it outputs:

Single-quote XML declaration: <?xml version='1.0' encoding='UTF-8' standalone='yes'?>
LF line endings (\n)

Original docx files (created by Word/WPS/OnlyOffice) use:

Double-quote XML declaration: <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
CRLF line endings (\r\n)

OnlyOffice cannot open docx files with single-quote XML declarations. The file appears structurally valid (ZIP ok, XML parses fine, python-docx loads it, even x2t can convert it to PDF), but the OnlyOffice web editor refuses to open it.

Affected Files

Only XML files that were re-serialized by lxml are affected. In a typical ContractEditor workflow:

word/document.xml — always re-serialized (main editing target)
word/settings.xml — re-serialized if trackRevisions was added/modified

Other XML files (styles.xml, fontTable.xml, theme1.xml, etc.) that were read and written back unchanged via zipfile retain their original format.

Diagnosis

import zipfile

def check_docx_xml_format(docx_path):
    """Check if any XML files have problematic single-quote declarations."""
    issues = []
    with zipfile.ZipFile(docx_path) as z:
        for name in z.namelist():
            if name.endswith('.xml') or name.endswith('.rels'):
                data = z.read(name).decode('utf-8')
                first_line = data.split('\n')[0]
                has_single_quotes = "version='1.0'" in first_line
                has_lf_only = '\r\n' not in data[:200]
                if has_single_quotes or has_lf_only:
                    issues.append((name, has_single_quotes, has_lf_only))
    return issues

Fix Script

import zipfile
import re
import os
import tempfile

def fix_xml_declarations(docx_path, output_path=None):
    """
    Fix lxml-serialized XML files inside a docx:
    1. Single quotes -> double quotes in XML declaration
    2. LF -> CRLF line endings (only if file has no CRLF)
    
    If output_path is None, fixes in-place (via temp file + rename).
    """
    if output_path is None:
        output_path = docx_path
    
    tmp_fd, tmp_path = tempfile.mkstemp(suffix='.docx')
    os.close(tmp_fd)
    
    try:
        with zipfile.ZipFile(docx_path, 'r') as zin:
            with zipfile.ZipFile(tmp_path, 'w', zipfile.ZIP_DEFLATED) as zout:
                for item in zin.infolist():
                    data = zin.read(item.filename)
                    
                    if item.filename.endswith('.xml') or item.filename.endswith('.rels'):
                        text = data.decode('utf-8')
                        
                        # Fix 1: Single quotes -> double quotes in XML declaration
                        text = re.sub(
                            r"<\?xml version='1\.0' encoding='UTF-8' standalone='yes'\?>",
                            '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>',
                            text
                        )
                        
                        # Fix 2: LF -> CRLF (only if no CRLF present)
                        if '\r\n' not in text and '\n' in text:
                            text = text.replace('\n', '\r\n')
                        
                        data = text.encode('utf-8')
                    
                    zout.writestr(item, data)
        
        os.replace(tmp_path, output_path)
    except:
        if os.path.exists(tmp_path):
            os.unlink(tmp_path)
        raise

# Usage after ContractEditor.save() or manual zipfile write:
# fix_xml_declarations('/tmp/【修】contract.docx')

Integration Points

After ContractEditor.save()

ed = ContractEditor(src)
# ... edits ...
ed.save(output_path)
fix_xml_declarations(output_path)  # Must run after every save

After manual zipfile+lxml write

with zipfile.ZipFile(output_path, 'w', zipfile.ZIP_DEFLATED) as zout:
    for item in zin.infolist():
        # ... write files ...
        pass

fix_xml_declarations(output_path)  # Must run after ZIP is closed

Key Insight

x2t (OnlyOffice converter CLI) tolerates single-quote declarations — it can convert the "broken" file to PDF successfully
The OnlyOffice web editor (WOPI-based document editing) does NOT tolerate single-quote declarations
python-docx Document() opens the file fine (lxml parses both formats)
Standard validation tools (zipfile.testzip(), etree.fromstring()) all pass

This makes the issue hard to diagnose — everything looks valid except OnlyOffice refuses to open it. The only reliable test is checking the raw bytes of the XML declaration in the ZIP.

4.7 KiB Raw Blame History