Parser and tests14 KB Selected work

Reads Word work instructions into structured data.

work_instruction.docx

Examples
Insert into the last paragraph

Enter new paragraph, Shift+Enter line break inside one, Backspace at the start joins it to the one above.

Accepted
Command lineexit 0
$ python sop_to_work_instruction.py work_instruction.docx --output-dir out

        

Refusal codes

If a document does not fit the template, the tool stops with one of these 42 codes and writes nothing.

42 codes

Input

Before anything is opened

  • INPUT_READ_FAILEDThe source file can't be read.CLI only
  • INPUT_SIZE_LIMITThe file is larger than 8 MiB.open a big file

ZIP package

Checked from the directory, before a member is read

  • ZIP_INVALIDNot a ZIP archive at all.open a non-ZIP file
  • ZIP_MEMBER_COUNT_LIMITMore than 256 members.
  • ZIP_DUPLICATE_MEMBERThe same member name appears twice.
  • ZIP_UNSAFE_MEMBERA name with a backslash, a colon, a leading slash or a dot segment.
  • ZIP_ENCRYPTED_MEMBERA member is encrypted.
  • ZIP_UNSUPPORTED_COMPRESSIONAnything other than stored or deflate.
  • ZIP_MEMBER_LIMITA member expands past 4 MiB, or past its own part limit.
  • ZIP_TOTAL_SIZE_LIMITAll members together expand past 16 MiB.
  • ZIP_COMPRESSION_RATIO_LIMITA member expands more than 250 times its compressed size.
  • UNSUPPORTED_PACKAGE_CONTENTMacros, ActiveX or embedded packages, by part name or content type.
  • ZIP_MEMBER_READ_FAILEDA required part fails to decompress or its checksum is wrong.
  • ZIP_SIZE_MISMATCHA part's bytes don't match the size the directory declared.

Parts and XML

The three parts the parser needs

  • DOCX_MISSING_PARTNo content types, root relationships or main document.
  • XML_UNSUPPORTED_ENCODINGA part is UTF-16, UTF-32 or not valid UTF-8.
  • XML_UNSAFE_DECLARATIONA DOCTYPE or ENTITY declaration.
  • XML_MALFORMEDA part is not well-formed XML.
  • DOCX_PART_ROOTA part has the wrong root element.
  • DOCX_CONTENT_TYPENo Word main document content type for word/document.xml.
  • DOCX_ROOT_RELATIONSHIPNot exactly one main document relationship, or it points elsewhere.
  • DOCX_BODY_MISSINGThe document has no body.

Word content

Anywhere in the document

  • UNSUPPORTED_TABLEAny table.
  • UNSUPPORTED_IMAGEDrawings, pictures, objects, text boxes or a media part.
  • UNSUPPORTED_NUMBERINGAutomatic Word numbering or lists.
  • UNSUPPORTED_WORD_CONTENTFields, tracked changes, comments, links, symbols, content controls.
  • UNSUPPORTED_HIDDEN_TEXTText formatted as hidden.
  • UNSUPPORTED_BODY_CONTENTAnything in the body other than paragraphs.
  • UNSUPPORTED_BREAK_TYPEA page or column break inside a paragraph.

Template

Paragraph by paragraph

  • TEMPLATE_MISSING_TITLEThe first non-empty paragraph isn't the title, or there is none.
  • TEMPLATE_EMPTY_TITLEThe title label has no text.
  • TEMPLATE_MULTILINE_TITLEThe title has a line break.
  • TEMPLATE_DUPLICATE_LABELA second title, safety notes or the same step number.
  • TEMPLATE_AMBIGUOUS_CONTENTAn unlabeled paragraph, or labels in the wrong order.
  • TEMPLATE_EMPTY_SAFETY_NOTESThe safety notes label has no text.
  • TEMPLATE_STEP_NUMBER_LIMITA step number longer than nine digits.
  • TEMPLATE_EMPTY_STEPA step label with no instruction.
  • TEMPLATE_NO_STEPSA title and no steps.
  • TEMPLATE_STEP_SEQUENCESteps that don't start at 1 or skip a number.

Output

Only after a clean parse

  • OUTPUT_DIR_UNAVAILABLEThe output folder can't be created or isn't a folder.CLI only
  • OUTPUT_EXISTSEither preview file is already there. Both are left as they were.CLI only
  • OUTPUT_WRITE_FAILEDPublishing failed. Any file already linked is removed again.CLI only

Output from the Python tool

The two files it wrote for the test file. Paragraphs are counted from 1.

work_instruction_preview.json860 bytes
{
  "parser_version": "1.0.0",
  "safety_notes": {
    "source_paragraph_index": 2,
    "text": "Synthetic example only.\nNo equipment is involved."
  },
  "schema_version": "work-instruction-preview/1",
  "source": {
    "filename": "synthetic_sop.docx",
    "paragraph_indexing": "One-based paragraphs in the main document body, including blank paragraphs.",
    "sha256": "4a68545d3a8b70d49bd683844b3f021e22797fb2b502c4aa2799cd87bb23d267",
    "size_bytes": 1081
  },
  "steps": [
    {
      "source_paragraph_index": 3,
      "step_number": 1,
      "text": "Open the sample record.\nCheck that the café record ID is present."
    },
    {
      "source_paragraph_index": 4,
      "step_number": 2,
      "text": "Mark the sample record Complete."
    }
  ],
  "title": {
    "source_paragraph_index": 1,
    "text": "Review a sample café record"
  }
}
work_instruction_preview.csv552 bytes
record_type,step_number,text,source_paragraph_index,source_sha256
title,,Review a sample café record,1,4a68545d3a8b70d49bd683844b3f021e22797fb2b502c4aa2799cd87bb23d267
safety_notes,,"Synthetic example only.
No equipment is involved.",2,4a68545d3a8b70d49bd683844b3f021e22797fb2b502c4aa2799cd87bb23d267
step,1,"Open the sample record.
Check that the café record ID is present.",3,4a68545d3a8b70d49bd683844b3f021e22797fb2b502c4aa2799cd87bb23d267
step,2,Mark the sample record Complete.,4,4a68545d3a8b70d49bd683844b3f021e22797fb2b502c4aa2799cd87bb23d267

Checking the editor against these files.

Formulas, size limits and tests

step text=SUM(A1:A9)
.csv'=SUM(A1:A9)
.json"=SUM(A1:A9)"

Applies to = + - @. Try "Text starting with =" in the examples.

sop_to_work_instruction.pylines 450 to 455
def _csv_safe_text(value: str) -> str:
    """Keep formula-like source text literal when a CSV is opened as a spreadsheet."""
    significant = value.lstrip()
    if significant.startswith(("=", "+", "-", "@")):
        return "'" + value
    return value

Python standard library only. The list of files inside the .docx is checked before anything is unpacked.

  • Source file 8 MiB
  • One member, expanded 4 MiB
  • All members, expanded 16 MiB
  • Members 256
  • Expansion ratio 250 to 1
rerun on 24 October 2026Python 3.12
$ python -m unittest tests.test_sop_to_work_instruction
Ran 28 tests in 0.558s
OK

Limits

One labeled template, not any Word file.

generated and damaged files
1,373
files built in the editor
600
differences
0
  • Reads a title, optional safety notes and one paragraph per step.
  • Does not read tables, automatic lists, headers or footers.
  • No upload, no MES connection, no production setup.

For a real project

Start with one anonymized real document. Agree the structure and field mapping, then test on known documents before connecting anything.