Reads Word work instructions into structured data.
Enter new paragraph, Shift+Enter line break inside one, Backspace at the start joins it to the one above.
$ 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.
Input
Before anything is opened
INPUT_READ_FAILEDThe source file can't be read.CLI onlyINPUT_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 fileZIP_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 onlyOUTPUT_EXISTSEither preview file is already there. Both are left as they were.CLI onlyOUTPUT_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.
{
"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"
}
}
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
=SUM(A1:A9)'=SUM(A1:A9)"=SUM(A1:A9)"Applies to = + - @. Try "Text starting with =" in the examples.
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
$ 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.