msdoc2docx 0.7.0__py3-none-any.whl

doc2docx/cfb/header.py

@@ -0,0 +1,108 @@
+"""CFB header parsing and validation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import struct
+
+from .constants import CFB_SIGNATURE, ENDOFCHAIN, FREESECT
+from ..errors import InvalidCompoundFile
+
+
+@dataclass(slots=True, frozen=True)
+class CompoundFileHeader:
+    minor_version: int
+    major_version: int
+    sector_size: int
+    mini_sector_size: int
+    number_of_directory_sectors: int
+    number_of_fat_sectors: int
+    first_directory_sector: int
+    transaction_signature: int
+    mini_stream_cutoff: int
+    first_mini_fat_sector: int
+    number_of_mini_fat_sectors: int
+    first_difat_sector: int
+    number_of_difat_sectors: int
+    difat: tuple[int, ...]
+
+    @classmethod
+    def parse(cls, data: bytes | memoryview) -> "CompoundFileHeader":
+        view = memoryview(data)
+        if len(view) < 512:
+            raise InvalidCompoundFile("CFB file is shorter than its 512-byte header")
+        if view[:8].tobytes() != CFB_SIGNATURE:
+            raise InvalidCompoundFile(
+                "input does not have the CFB/OLE compound-file signature"
+            )
+        if any(view[8:24]):
+            raise InvalidCompoundFile("CFB header CLSID must be zero")
+
+        minor, major, byte_order, sector_shift, mini_shift = struct.unpack_from(
+            "<HHHHH", view, 24
+        )
+        if byte_order != 0xFFFE:
+            raise InvalidCompoundFile(
+                f"unsupported CFB byte order 0x{byte_order:04X}"
+            )
+        if major not in (3, 4):
+            raise InvalidCompoundFile(f"unsupported CFB major version {major}")
+        expected_shift = 9 if major == 3 else 12
+        if sector_shift != expected_shift:
+            raise InvalidCompoundFile(
+                f"CFB version {major} requires sector shift {expected_shift}, "
+                f"got {sector_shift}"
+            )
+        if mini_shift != 6:
+            raise InvalidCompoundFile(
+                f"CFB mini-sector shift must be 6, got {mini_shift}"
+            )
+        if any(view[34:40]):
+            raise InvalidCompoundFile("reserved CFB header bytes must be zero")
+
+        fields = struct.unpack_from("<IIIIIIIII", view, 40)
+        (
+            number_of_directory_sectors,
+            number_of_fat_sectors,
+            first_directory_sector,
+            transaction_signature,
+            mini_stream_cutoff,
+            first_mini_fat_sector,
+            number_of_mini_fat_sectors,
+            first_difat_sector,
+            number_of_difat_sectors,
+        ) = fields
+        if major == 3 and number_of_directory_sectors != 0:
+            raise InvalidCompoundFile(
+                "CFB version 3 must declare zero directory sectors"
+            )
+        if mini_stream_cutoff != 0x1000:
+            raise InvalidCompoundFile(
+                f"CFB mini-stream cutoff must be 4096, got {mini_stream_cutoff}"
+            )
+        difat = struct.unpack_from("<109I", view, 76)
+
+        if number_of_difat_sectors == 0 and first_difat_sector not in (
+            ENDOFCHAIN,
+            FREESECT,
+        ):
+            raise InvalidCompoundFile(
+                "CFB header has no DIFAT sectors but a non-free first DIFAT sector"
+            )
+
+        return cls(
+            minor,
+            major,
+            1 << sector_shift,
+            1 << mini_shift,
+            number_of_directory_sectors,
+            number_of_fat_sectors,
+            first_directory_sector,
+            transaction_signature,
+            mini_stream_cutoff,
+            first_mini_fat_sector,
+            number_of_mini_fat_sectors,
+            first_difat_sector,
+            number_of_difat_sectors,
+            tuple(difat),
+        )

doc2docx/cli.py

@@ -0,0 +1,100 @@
+"""Command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+from typing import Sequence
+
+from . import __version__
+from .cfb import CompoundFileLimits
+from .converter import convert, inspect_doc
+from .errors import Doc2DocxError
+
+
+def _limits(value: int) -> CompoundFileLimits:
+    return CompoundFileLimits(max_input_bytes=value)
+
+
+def _inspection_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="doc2docx inspect")
+    parser.add_argument("input", type=Path)
+    parser.add_argument("--json", action="store_true", dest="as_json")
+    parser.add_argument(
+        "--max-input-bytes", type=int, default=CompoundFileLimits().max_input_bytes
+    )
+    return parser
+
+
+def _conversion_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="doc2docx",
+        description="Convert an unencrypted Word 97-2003 .doc file to .docx",
+    )
+    parser.add_argument("input", type=Path)
+    parser.add_argument("-o", "--output", type=Path)
+    parser.add_argument("--report", type=Path)
+    parser.add_argument(
+        "--max-input-bytes", type=int, default=CompoundFileLimits().max_input_bytes
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+    return parser
+
+
+def _print_inspection(info: dict[str, object]) -> None:
+    cfb = info["cfb"]
+    fib = info["fib"]
+    assert isinstance(cfb, dict) and isinstance(fib, dict)
+    print(f"Input: {info['path']}")
+    print(
+        f"CFB: version {cfb['major_version']}, sector size {cfb['sector_size']}, "
+        f"{cfb['sector_count']} sectors"
+    )
+    print(
+        f"FIB: nFib=0x{int(fib['nFib']):04X}, table={fib['table_stream']}, "
+        f"ccpText={fib['ccpText']}, encrypted={fib['encrypted']}"
+    )
+    print("Streams and storages:")
+    entries = info["entries"]
+    assert isinstance(entries, list)
+    for item in entries:
+        size = "" if item["size"] is None else f" ({item['size']} bytes)"
+        print(f"  {item['type']:12} {item['path']}{size}")
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    arguments = list(sys.argv[1:] if argv is None else argv)
+    try:
+        if arguments[:1] == ["inspect"]:
+            args = _inspection_parser().parse_args(arguments[1:])
+            info = inspect_doc(
+                args.input,
+                limits=_limits(args.max_input_bytes),
+            )
+            if args.as_json:
+                print(json.dumps(info, ensure_ascii=False, indent=2))
+            else:
+                _print_inspection(info)
+            return 0
+
+        args = _conversion_parser().parse_args(arguments)
+        result = convert(
+            args.input,
+            args.output,
+            limits=_limits(args.max_input_bytes),
+        )
+        if args.report:
+            result.report.write_json(args.report)
+        print(f"Converted {args.input} -> {result.output_path}")
+        if result.report.warnings:
+            print(
+                f"Completed with {len(result.report.warnings)} warning(s)",
+                file=sys.stderr,
+            )
+        return 0
+    except (Doc2DocxError, OSError) as exc:
+        print(f"doc2docx: error: {exc}", file=sys.stderr)
+        return 2
+

doc2docx/converter.py

@@ -0,0 +1,321 @@
+"""End-to-end conversion and inspection APIs."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+import os
+from pathlib import Path
+import stat
+import tempfile
+from typing import Any
+
+from .cfb import CompoundFile, CompoundFileLimits, ObjectType
+from .diagnostics import ConversionReport
+from .errors import (
+    EncryptedDocumentError,
+    InvalidWordDocument,
+    UnsafeOutputPathError,
+)
+from .model import Document, Paragraph, Table, parse_main_story
+from .msdoc import (
+    FileInformationBlock,
+    read_document_settings,
+    read_font_table,
+    read_formatting,
+    read_header_footer_stories,
+    read_piece_table,
+    read_sections,
+    read_style_sheet,
+)
+from .ooxml import validate_docx, write_docx
+
+
+@dataclass(slots=True, frozen=True)
+class ConversionResult:
+    output_path: Path
+    report: ConversionReport
+    document: Document
+
+
+def _iter_tables(blocks: Iterable[Paragraph | Table]) -> Iterator[Table]:
+    for block in blocks:
+        if not isinstance(block, Table):
+            continue
+        yield block
+        for row in block.rows:
+            for cell in row.cells:
+                yield from _iter_tables(cell.body_blocks)
+
+
+def _load_word_parts(
+    source: str | Path,
+    *,
+    limits: CompoundFileLimits | None,
+) -> tuple[CompoundFile, bytes, FileInformationBlock]:
+    compound = CompoundFile.from_path(source, limits=limits)
+    word_document = compound.open_stream("WordDocument")
+    fib = FileInformationBlock.parse(word_document)
+    return compound, word_document, fib
+
+
+def convert(
+    source: str | Path,
+    destination: str | Path | None = None,
+    *,
+    limits: CompoundFileLimits | None = None,
+) -> ConversionResult:
+    source_path = Path(source)
+    destination_path = (
+        Path(destination) if destination is not None else source_path.with_suffix(".docx")
+    )
+    if destination_path.suffix.lower() != ".docx":
+        raise UnsafeOutputPathError("destination must use the .docx extension")
+    if source_path.resolve() == destination_path.resolve():
+        raise UnsafeOutputPathError("destination must not overwrite the source document")
+    report = ConversionReport(str(source_path), str(destination_path))
+
+    compound, word_document, fib = _load_word_parts(source_path, limits=limits)
+    repaired_entries = [entry for entry in compound.entries if entry.name_was_repaired]
+    if repaired_entries:
+        report.warning(
+            "CFB_DIRECTORY_REPAIRED",
+            "a malformed root directory name was safely normalized",
+            entry_count=len(repaired_entries),
+        )
+    if fib.base.is_encrypted:
+        method = "XOR obfuscation" if fib.base.is_obfuscated else "RC4 encryption"
+        raise EncryptedDocumentError(
+            f"password-protected Word documents using {method} are not yet supported"
+        )
+
+    table_name = fib.base.table_stream_name
+    table_stream = compound.open_stream(table_name)
+    section_table = fib.plcf_sed
+    sections = read_sections(
+        table_stream,
+        word_document,
+        offset=section_table.fc,
+        size=section_table.lcb,
+        main_story_cp_count=fib.ccp_text,
+        document_lid=fib.base.lid,
+        report=report,
+    )
+    dop = fib.dop
+    document_settings = read_document_settings(
+        table_stream,
+        offset=dop.fc,
+        size=dop.lcb,
+    )
+    font_table = fib.sttbf_ffn
+    fonts = read_font_table(
+        table_stream,
+        offset=font_table.fc,
+        size=font_table.lcb,
+    )
+    style_table = fib.stshf
+    style_sheet = read_style_sheet(
+        table_stream,
+        offset=style_table.fc,
+        size=style_table.lcb,
+        fonts=fonts,
+        report=report,
+    )
+    clx = fib.clx
+    piece_table = read_piece_table(
+        table_stream,
+        word_document,
+        fc_clx=clx.fc,
+        lcb_clx=clx.lcb,
+        report=report,
+    )
+    if fib.ccp_text > piece_table.cp_end:
+        raise InvalidWordDocument(
+            f"FIB main-story length {fib.ccp_text} exceeds Piece Table range "
+            f"{piece_table.cp_end}"
+        )
+    chpx = fib.plcf_bte_chpx
+    papx = fib.plcf_bte_papx
+    formatting = read_formatting(
+        table_stream,
+        word_document,
+        piece_table,
+        fc_plcf_bte_chpx=chpx.fc,
+        lcb_plcf_bte_chpx=chpx.lcb,
+        fc_plcf_bte_papx=papx.fc,
+        lcb_plcf_bte_papx=papx.lcb,
+        report=report,
+        fonts=fonts,
+        style_sheet=style_sheet,
+    )
+    header_table = fib.plcf_hdd
+    header_footers = read_header_footer_stories(
+        table_stream,
+        piece_table,
+        sections,
+        offset=header_table.fc,
+        size=header_table.lcb,
+        ccp_headers=fib.ccp_headers,
+        header_story_cp_start=fib.header_story_cp_start,
+        report=report,
+        character_properties_at=formatting.character_properties_at,
+        paragraph_properties_at=formatting.paragraph_properties_at,
+    )
+    sections = header_footers.sections
+    main_characters = piece_table.extract_characters(
+        0,
+        fib.ccp_text,
+        report,
+        story="main",
+    )
+    parsed_document = parse_main_story(
+        main_characters,
+        report,
+        character_properties_at=formatting.character_properties_at,
+        paragraph_properties_at=formatting.paragraph_properties_at,
+        sections=sections,
+    )
+    document = Document(
+        paragraphs=parsed_document.paragraphs,
+        fonts=fonts,
+        styles=style_sheet,
+        blocks=parsed_document.blocks,
+        sections=sections,
+        even_and_odd_headers=document_settings.even_and_odd_headers,
+    )
+    tables = tuple(_iter_tables(document.body_blocks))
+
+    report.statistics.update(
+        {
+            "cfb_sector_count": compound.sector_count,
+            "table_stream": table_name,
+            "fib_version": fib.n_fib,
+            "piece_count": len(piece_table.pieces),
+            "main_story_cp_count": fib.ccp_text,
+            "paragraph_count": len(document.paragraphs),
+            "character_format_span_count": len(formatting.character_spans),
+            "paragraph_format_span_count": len(formatting.paragraph_spans),
+            "character_fkp_run_count": formatting.character_fkp_run_count,
+            "paragraph_fkp_run_count": formatting.paragraph_fkp_run_count,
+            "font_count": len(fonts),
+            "style_count": sum(
+                1 for style in style_sheet.styles if style is not None
+            ),
+            "piece_prm_count": sum(
+                1 for piece in piece_table.pieces if piece.prm
+            ),
+            "clx_prc_count": len(piece_table.prcs),
+            "table_count": len(tables),
+            "table_row_count": sum(len(table.rows) for table in tables),
+            "table_cell_count": sum(
+                len(row.cells) for table in tables for row in table.rows
+            ),
+            "section_count": len(sections),
+            "header_footer_story_count": header_footers.story_count,
+            "header_footer_paragraph_count": header_footers.paragraph_count,
+        }
+    )
+    if fib.base.has_pictures:
+        report.warning(
+            "PICTURES_DEFERRED",
+            "the FIB reports pictures; picture conversion is not yet supported",
+        )
+    secondary_stories = fib.secondary_story_character_counts
+    secondary_stories.pop("headers", None)
+    if secondary_stories:
+        report.warning(
+            "SECONDARY_STORIES_DEFERRED",
+            "some secondary document stories remain unsupported after M5b",
+            stories=secondary_stories,
+        )
+
+    destination_path.parent.mkdir(parents=True, exist_ok=True)
+    destination_mode = (
+        stat.S_IMODE(destination_path.stat().st_mode)
+        if destination_path.exists()
+        else 0o644
+    )
+    temporary_path: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            prefix=f".{destination_path.name}.",
+            suffix=".tmp",
+            dir=destination_path.parent,
+            delete=False,
+        ) as temporary:
+            temporary_path = Path(temporary.name)
+        write_docx(document, temporary_path)
+        validate_docx(temporary_path)
+        os.chmod(temporary_path, destination_mode)
+        os.replace(temporary_path, destination_path)
+        temporary_path = None
+    finally:
+        if temporary_path is not None:
+            try:
+                temporary_path.unlink()
+            except FileNotFoundError:
+                pass
+
+    report.info("CONVERSION_COMPLETE", "M0-M5b conversion completed")
+    return ConversionResult(destination_path, report, document)
+
+
+def inspect_doc(
+    source: str | Path,
+    *,
+    limits: CompoundFileLimits | None = None,
+) -> dict[str, Any]:
+    compound, _, fib = _load_word_parts(source, limits=limits)
+    entries = []
+    for entry in compound.entries:
+        if entry.path == "":
+            continue
+        entries.append(
+            {
+                "path": entry.path,
+                "type": entry.object_type.name.lower(),
+                "size": entry.stream_size
+                if entry.object_type is ObjectType.STREAM
+                else None,
+                "starting_sector": entry.starting_sector,
+            }
+        )
+    return {
+        "path": str(Path(source)),
+        "cfb": {
+            "major_version": compound.header.major_version,
+            "minor_version": compound.header.minor_version,
+            "sector_size": compound.header.sector_size,
+            "mini_sector_size": compound.header.mini_sector_size,
+            "sector_count": compound.sector_count,
+            "directory_repairs": sum(
+                1 for entry in compound.entries if entry.name_was_repaired
+            ),
+        },
+        "fib": {
+            "nFib": fib.n_fib,
+            "lid": fib.base.lid,
+            "encrypted": fib.base.is_encrypted,
+            "obfuscated": fib.base.is_obfuscated,
+            "table_stream": fib.base.table_stream_name,
+            "ccpText": fib.ccp_text,
+            "ccpHdd": fib.ccp_headers,
+            "fcClx": fib.clx.fc,
+            "lcbClx": fib.clx.lcb,
+            "fcPlcfBteChpx": fib.plcf_bte_chpx.fc,
+            "lcbPlcfBteChpx": fib.plcf_bte_chpx.lcb,
+            "fcPlcfBtePapx": fib.plcf_bte_papx.fc,
+            "lcbPlcfBtePapx": fib.plcf_bte_papx.lcb,
+            "fcStshf": fib.stshf.fc,
+            "lcbStshf": fib.stshf.lcb,
+            "fcPlcfSed": fib.plcf_sed.fc,
+            "lcbPlcfSed": fib.plcf_sed.lcb,
+            "fcPlcfHdd": fib.plcf_hdd.fc,
+            "lcbPlcfHdd": fib.plcf_hdd.lcb,
+            "fcDop": fib.dop.fc,
+            "lcbDop": fib.dop.lcb,
+            "fcSttbfFfn": fib.sttbf_ffn.fc,
+            "lcbSttbfFfn": fib.sttbf_ffn.lcb,
+        },
+        "entries": sorted(entries, key=lambda item: item["path"]),
+    }

doc2docx/diagnostics.py

@@ -0,0 +1,105 @@
+"""Structured diagnostics emitted during inspection and conversion."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from enum import StrEnum
+import json
+from pathlib import Path
+from typing import Any
+
+
+class Severity(StrEnum):
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+
+
+@dataclass(slots=True, frozen=True)
+class SourceLocation:
+    story: str | None = None
+    cp_start: int | None = None
+    cp_end: int | None = None
+    stream: str | None = None
+    fc_start: int | None = None
+    fc_end: int | None = None
+
+
+@dataclass(slots=True, frozen=True)
+class Diagnostic:
+    severity: Severity
+    code: str
+    message: str
+    location: SourceLocation | None = None
+    details: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        result = asdict(self)
+        result["severity"] = self.severity.value
+        if self.location is None:
+            result.pop("location")
+        if not self.details:
+            result.pop("details")
+        return result
+
+
+@dataclass(slots=True)
+class ConversionReport:
+    source: str
+    destination: str | None = None
+    diagnostics: list[Diagnostic] = field(default_factory=list)
+    statistics: dict[str, int | str | bool] = field(default_factory=dict)
+
+    def add(
+        self,
+        severity: Severity,
+        code: str,
+        message: str,
+        *,
+        location: SourceLocation | None = None,
+        **details: Any,
+    ) -> None:
+        self.diagnostics.append(
+            Diagnostic(severity, code, message, location, details)
+        )
+
+    def info(self, code: str, message: str, **details: Any) -> None:
+        self.add(Severity.INFO, code, message, **details)
+
+    def warning(
+        self,
+        code: str,
+        message: str,
+        *,
+        location: SourceLocation | None = None,
+        **details: Any,
+    ) -> None:
+        self.add(
+            Severity.WARNING,
+            code,
+            message,
+            location=location,
+            **details,
+        )
+
+    def error(self, code: str, message: str, **details: Any) -> None:
+        self.add(Severity.ERROR, code, message, **details)
+
+    @property
+    def warnings(self) -> list[Diagnostic]:
+        return [d for d in self.diagnostics if d.severity is Severity.WARNING]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "source": self.source,
+            "destination": self.destination,
+            "statistics": dict(self.statistics),
+            "diagnostics": [item.to_dict() for item in self.diagnostics],
+        }
+
+    def write_json(self, path: str | Path) -> None:
+        Path(path).write_text(
+            json.dumps(self.to_dict(), ensure_ascii=False, indent=2) + "\n",
+            encoding="utf-8",
+        )
+

doc2docx/errors.py

@@ -0,0 +1,37 @@
+"""Domain-specific exceptions raised by the converter."""
+
+
+class Doc2DocxError(Exception):
+    """Base class for expected conversion failures."""
+
+
+class BinaryBoundsError(Doc2DocxError):
+    """A binary structure tried to read outside its declared bounds."""
+
+
+class InvalidCompoundFile(Doc2DocxError):
+    """The input is not a valid or safely readable CFB/OLE compound file."""
+
+
+class StreamNotFound(InvalidCompoundFile):
+    """A required stream is absent from the compound file."""
+
+
+class InvalidWordDocument(Doc2DocxError):
+    """The compound file is not a supported MS-DOC Word document."""
+
+
+class EncryptedDocumentError(Doc2DocxError):
+    """The input requires a password/decryption implementation."""
+
+
+class UnsupportedFeatureError(Doc2DocxError):
+    """A valid feature is outside the currently supported milestone."""
+
+
+class PackageWriteError(Doc2DocxError):
+    """The DOCX package could not be generated safely."""
+
+
+class UnsafeOutputPathError(Doc2DocxError):
+    """The requested destination could overwrite the source or is not DOCX."""