docx

Files (5)

• SKILL.md
• reference.md
• extract_docx.py · scripts/
• inspect_docx.py · scripts/
• replace_text.py · scripts/

SKILL.md (first lines)

Read this page, then open only what you need: `reference.md` for format details,
`scripts/` for working tools. Run the scripts — do not rewrite them inline.

`python-docx` installs on import in every RunPython engine. Files persist
between calls in a chat, so work in steps.

## Before editing someone's document — inspect it

Never edit blind. Paragraph indices shift as soon as you insert, table text is
invisible to `doc.paragraphs`, and a "heading" is often just bolded text.

```
python scripts/inspect_docx.py report.docx
python scripts/inspect_docx.py report.docx --runs   # also show run splits
```

Prints styles in use, every paragraph with its style, tables, headers and
footers — and warns when the document contains fields (table of contents, page
numbers) that cannot be recomputed.

## Replacing text — use the script

This is the trap that ruins documents. Word splits a paragraph into *runs* for
invisible reasons (a spell-check pass, a tracked edit, where the cursor sat), so
the string you are looking for is frequently cut in half:

```
["Invoice ", "num", "ber ", "INV-", "001"]
```

`run.text.replace(...)` therefore finds nothing, and `paragraph.text = ...`
"works" by deleting every run — taking all bold, italics, colour, links and
fonts in that paragraph with it.

```
python scripts/replace_text.py in.docx out.docx "INV-001" "INV-777"
python scripts/replace_text.py in.docx out.docx --map replacements.json
```

Matches across run boundaries, writes into the first run of the match so
formatting is inherited, and also covers table cells, headers and footers.

## Extracting content — use the script

The usual one-liner over `doc.paragraphs` silently drops every table, header,
footer and footnote — which in a contract is where the content lives. It also
reorders the document, because python-docx exposes paragraphs and tables as two
separate lists.

```
python scripts/extract_docx.py report.docx            # markdown, in order
python scripts/extract_docx.py report.docx --json     # structured
```

## Creating a document

Build with real styles, never manual formatting: a heading made by enlarging
bold text is invisible to the navigation pane, to a table of contents and to a
screen reader.

```python
from docx import Document
from docx.shared import Cm

doc = Document()                  # or Document('template.docx') to keep branding
doc.add_heading('Quarterly report', level=0)
doc.add_heading('Revenue', level=1)

p = doc.add_paragraph('Revenue grew ')
p.add_run('12%').bold = True
p.add_run(' year over year.')

t = doc.add_table(rows=1, cols=3)
t.style = 'Light Grid Accent 1'
for c, h in zip(t.rows[0].cells, ['Region', 'Q3', 'Q4']):
    c.text = h
cells = t.add_row().cells
for c, v in zip(cells, ('North', '23 771', '25 104')):
    c.text = v

doc.add_picture('chart.png', width=Cm(15))   # generate it in an earlier call
doc.save('report.docx')
```

If the user supplies a template, open **that file** as the document — that is
what preserves their fonts, colours and styles. Never rebuild branding by hand.

`reference.md` covers style names, sections and page setup, headers and footers,
lists, cell merging and shading, and images.

## Limits — say these instead of pretending

- **A table of contents cannot be recomputed.** You can insert the field, but it
  stays empty until the user opens the file and presses Ctrl+A, F9. Tell them.
- **Tracked changes and comments** are not exposed by the python-docx API.
- **Page count and page breaks** are decided by Word's layout engine — you
  cannot know the final pagination.

## Verify before claiming success

A file that exists is not a file that is correct. Reopen it and check content:

```python
from docx import Document
d = Document('report.docx')
assert any('Revenue' in p.text for p in d.paragraphs), 'heading missing'
print(len(d.paragraphs), 'paragraphs,', len(d.tables), 'tables')
```

If generation failed, report the real error. Never quietly deliver a different
format than the one requested.

From iaa2005/monet-directory, MIT.

More from iaa2005/monet-directory