Skip to content

DIF, Markdown import, and byte-level format inspection

The commercial wolfxl_pro.formats module provides these APIs without changing the core Workbook.save or wolfxl.load_workbook dispatch:

from pathlib import Path
from wolfxl_pro.formats import DifSaveOptions, MarkdownLoadOptions, FileFormatUtil

from wolfxl_pro.dif import load_dif

DifSaveOptions(cell_range="B2:E20").save(worksheet, Path("selected.dif"))
dif_book = load_dif(Path("selected.dif"))
book = MarkdownLoadOptions().load(Path("export.md"))
MarkdownLoadOptions().load("| A | B |\n|---|---|\n|1|2|\n", worksheet=worksheet)
info = FileFormatUtil.detect_file_format(Path("unknown-file").read_bytes())
print(info.file_format_type, info.is_encrypted)

DIF

DifSaveOptions.to_bytes(sheet) returns UTF-8 DIF by default; save accepts a path or binary writable stream. The default selection starts at A1 and includes the worksheet's used dimensions; an explicit A1 rectangle exports only that range. Headers are TABLE, VECTORS (columns), TUPLES (rows), and DATA. Every row begins with BOT and the document terminates with EOD. Numbers use numeric V records, booleans TRUE/FALSE records, text quoted records with doubled quotes, and blanks empty text records. Unsupported scalar types and non-finite numbers raise rather than silently changing their meaning. Styles and formulas are not a DIF capability: use a data-only loaded worksheet to export cached formula values.

Use wolfxl_pro.dif.load_dif(source) to import a validated scalar rectangle into a new editable workbook, or pass worksheet=... to populate an existing worksheet atomically. The existing reader supports bytes, text, paths and readable streams. Numeric temporal serials remain numbers; empty strings become blanks. Invalid or unsupported input is refused with dif_import_invalid or dif_import_unsupported. Explicitly save the workbook to write XLSX output. LoadFormat.DIF describes this reader without extending the core workbook loader.

The headless LibreOffice import proof compares actual cell values. LibreOffice stores standard DIF TRUE/FALSE records as numeric 1/0 when converting to XLSX, so logical values remain equal but Boolean scalar types are not preserved by that importer. The committed comparison retains both original Boolean expectations and raw numeric oracle cells.

Markdown

MarkdownLoadOptions.load accepts Markdown text, bytes, a Path, or a readable stream. It returns a workbook, or the supplied worksheet when exactly one table is present. Header cells become the first worksheet row; alignment delimiters are not values. Pipe escapes, inline backtick code, the existing exporter's \\n/\\t/\\\\ escapes, blank cells, booleans, and grouped/scientific numeric text are supported. Set infer_numbers=False to retain nonblank values as text. Code-span values remain text. Multiple tables and the existing exporter's ## Sheet name headings retain their names. Ragged rows are rejected.

The existing Markdown export is a presentation format, not an injective serialization. General-format scalar fixtures round-trip identical values, but numeric-looking strings, empty strings versus blanks, custom number formats, dates rendered as text, rounded float output, and literal Markdown code spans cannot always recover their original types or precision. Loading cannot reconstruct information absent from the export. Use XLSX or a typed data format for lossless arbitrary-workbook serialization.

Typed format inspection

detect_file_format(bytes) and FileFormatUtil.detect_file_format(bytes) return immutable FileFormatInfo(file_format_type, is_encrypted). ZIP content types distinguish XLSX, XLSM and templates; xl/workbook.bin distinguishes XLSB; ODS uses its MIME part. CFB directory streams distinguish XLS from encrypted OOXML, and BIFF FilePass indicates encrypted XLS. An encrypted OOXML envelope cannot disclose the inner subtype, so it reports XLSX with the encrypted flag rather than guessing XLSM/XLSB. Unrecognized containers and ambiguous text return UNKNOWN. CSV/TSV detection requires at least two rectangular multi-field rows. HTML, DIF, Markdown, JSON, SpreadsheetML 2003, PDF and PNG are recognized from bytes.

DOCX, PPTX and XPS are detection-only kinds. Recognition requires matching main-part content types, one owning internal root relationship, and the corresponding XML root. Duplicate ownership, competing recognized markers, malformed manifests and inspection-limit violations return UNKNOWN. Inspection is inert ZIP/XML parsing, without another document engine. Numbers packages use the existing member classifier, including legacy Index.zip and encryption markers; use the public wolfxl.load_workbook reader to validate and import supported tables.

LoadFormat enumerates workbook and explicit worksheet-import APIs, including DIF and load-only Numbers. SaveFormat includes DIF worksheet export plus output-only PDF/PNG/TXT. Enumerations do not imply core workbook save/load support. Registry descriptors for DOCX/PPTX/XPS have no load, save or conversion direction; Numbers has only load, and DIF has load/save through its explicit APIs. Unsupported conversion destinations retain the existing named refusal. No new converter or document reader is supplied by format detection.

Transcription references

  • Microsoft MS-CFB sections 2.2–2.6 define CFB headers, FAT, mini FAT and directory entries.
  • Microsoft MS-XLS FilePass defines BIFF record 0x002F.
  • GFM tables and code spans define table headers and alignment delimiters.
  • WolfXL's Markdown table export defines the authoritative export shape and escape mapping.
  • DIF format reference documents TABLE/VECTORS/TUPLES/DATA and BOT/EOD scalar records; committed LibreOffice import comparisons provide independent interoperability proof.